![\"\"](\"src/Icon/asset/oakd_IconDownload.svg\"){kind=icon}
**Installation**\n\nTo start using `oakd`, install it via npm:\n\n```sh\nnpm install oakd\n```\n\n`react` and `react-dom` should already exist in the consuming application.\n\nThen, **import the styles** in your `App.tsx` (or wherever you use `oakd` components):\n\n```tsx\nimport \"oakd/build/index.css\";\n```\n\n---\n\n## ![\"\"](\"src/Icon/asset/oakd_IconPin.svg\"){kind=icon}
**Usage Example**\n\nAfter installation, use components like:\n\n```tsx\nimport React from \"react\";\nimport \"oakd/build/index.css\";\nimport { Title, Paragraph } from \"oakd\";\n\nconst App = () => (\n ![\"\"](\"src/Icon/asset/oakd_IconPaintbrush.svg\"){kind=icon}
**Icon Pack & Generation**\n\nThe oakd icon pack is custom-designed for OakFrame. All SVG icons are stored in the `src/Icon/asset/` folder. Follow these steps to update or add icons:\n\n1. **Add or update SVG files**: \n Place your SVG files in the `src/Icon/asset/` directory. File names should follow this pattern:\n\n ```\n oakd_Icon[A-Z][a-z+].svg\n ```\n\n2. **Run the icon generation script**: \n Use the following command to generate the icon exports:\n\n ```sh\n npm run icons\n ```\n\n This script creates a file named `src/Icon/Icons.bin.tsx`, which includes:\n - An `iconMap` object mapping icon names to components (e.g., `{ Angle: IAngle, Trash: ITrash }`).\n - Individual icon components (e.g., `IconTrash`, `IconUser`, etc.).\n\n3. **Icons are automatically included**: \n Once the script runs, all icons are ready to use with proper paths and inlined assets.\n\n---\n\n## ![\"\"](\"src/Icon/asset/oakd_IconCode.svg\"){kind=icon}
**Development**\n\n### ![\"\"](\"src/Icon/asset/oakd_IconCheck.svg\"){kind=icon}
**Testing**\n\nRun all tests using Jest:\n\n```sh\nnpm run test\n```\n\nJest is configured to:\n\n- Use `ts-jest` for TypeScript support.\n- Ignore `node_modules/`.\n- Output coverage reports in the `coverage/` directory.\n\n### ![\"\"](\"src/Icon/asset/oakd_IconHammer.svg\"){kind=icon}
**Building**\n\nCompile the library for production:\n\n```sh\nnpm run build\n```\n\n**Rollup is configured to:**\n\n- Output both CommonJS (`build/index.js`) and ES modules (`build/index.esm.js`).\n- Copy `index.css` to `build/` automatically.\n- Support image imports with `@rollup/plugin-image`.\n\n### ![\"\"](\"src/Icon/asset/oakd_IconBook.svg\"){kind=icon}
**Storybook**\n\nStart a live-reloading Storybook instance:\n\n```sh\nnpm run storybook\n```\n\nExport Storybook as static files:\n\n```sh\nnpm run storybook:export\n```\n\nServe the generated `storybook-static/` folder.\n\n---\n\n## ![\"\"](\"src/Icon/asset/oakd_IconWand.svg\"){kind=icon}
**Generating New Components**\n\nEasily scaffold a new component using:\n\n```sh\nnpm run generate YourComponentName\n```\n\nThis generates:\n\n```sh\n/src/YourComponentName\n ├── YourComponentName.tsx\n ├── YourComponentName.mdx\n ├── YourComponentName.stories.tsx\n ├── YourComponentName.test.tsx\n ├── YourComponentName.types.ts\n ├── YourComponentName.css\n```\n\nModify templates under `util/templates` as needed. \nDon’t forget to export your new component in `index.ts`!\n\n---\n\n## ![\"\"](\"src/Icon/asset/oakd_IconWrench.svg\"){kind=icon}
**Linting & Formatting**\n\nThe project uses ESLint with a configuration that:\n\n- Enforces best practices for TypeScript and React.\n- Uses Prettier (configured to use tabs).\n- Ignores generated or binary files (e.g. `*.bin.tsx`) from coverage.\n\n```sh\nnpm run lint\n```\n\nIf you want to run the ESLint with fix:\n\n```sh\nnpm run lint:fix\n```\n\n---\n\n## ![\"\"](\"src/Icon/asset/oakd_IconOpenExternal.svg\"){kind=icon}
**Installing Locally**\n\nTo test `oakd` in another project (`test-app`) **without publishing**, run:\n\n```sh\nnpm i --save ../oakd\n```\n\nThis adds an entry in `package.json`:\n\n```json\n\"dependencies\": {\n \"oakd\": \"file:../oakd\"\n}\n```\n\n### ![\"\"](\"src/Icon/asset/oakd_IconAlert.svg\"){kind=icon}
**Common Issue: Invalid Hook Call**\n\nIf you see:\n\n```sh\nInvalid hook call. Hooks can only be called inside the body of a function component.\n```\n\nThis likely means multiple versions of React are installed. \nFix it by linking React from the consuming app:\n\n```sh\nnpm link ../test-app/node_modules/react\n```\n\nAlternatively, configure Webpack as suggested [here](https://github.com/facebook/react/issues/13991#issuecomment-435587809).\n\n---\n\n## ![\"\"](\"src/Icon/asset/oakd_IconCloudSync.svg\"){kind=icon}
**Publishing**\n\n### ![\"\"](\"src/Icon/asset/oakd_IconShare.svg\"){kind=icon}
**Publishing to NPM**\n\nEnsure you're logged in:\n\n```sh\nnpm login\n```\n\nUpdate `package.json` with your NPM package name, then publish:\n\n```sh\nnpm publish\n```\n\nThe `\"prepublishOnly\": \"npm run build\"` script ensures a fresh build before publishing.\n\n### ![\"\"](\"src/Icon/asset/oakd_IconCloud.svg\"){kind=icon}
**Hosting via GitHub**\n\nAlternatively, push the built package to GitHub and install it via:\n\n```sh\nnpm i --save git+https://github.com/arkamedus/oakd.git#branch-name\n```\n\nor\n\n```sh\nnpm i --save github:arkamedus/oakd#branch-name\n```\n\n---\n\n## ![\"\"](\"src/Icon/asset/oakd_IconPaintPalette.svg\"){kind=icon}
**Styling**\n\nOakD retains global system light/dark theming. Its stable customization tokens\nuse the `--oakd-*` prefix, including `--oakd-background`, `--oakd-font-color`,\n`--oakd-font-family`, `--oakd-font-family-display`, `--oakd-leading`,\n`--oakd-gap`, `--oakd-radius`, and semantic color/border/text token sets.\n\nUse the original composition model for normal document layout:\n\n- `Page` owns page-level height and fixed behavior.\n- `Content`, `Row`, `Col`, and `Space` own flow and grid composition.\n- `Card` is a bordered semantic surface.\n- `AppShell`, `ScrollArea`, and `Dock` are for explicit application or\n editor-region ownership.\n\n### **Importing Styles**\n\nInclude the library’s styles in your project:\n\n```tsx\nimport \"oakd/build/index.css\";\n```\n\n### **Using CSS Variables**\n\nUtilize predefined CSS variables from `variables.css`:\n\n```css\n.example-container {\n color: var(--oakd-white);\n background-color: var(--oakd-black);\n}\n```\n\nMore on [CSS Variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties).\n\n---\n\n## ![\"\"](\"src/Icon/asset/oakd_IconCog.svg\"){kind=icon}
**Additional Features**\n\n### ![\"\"](\"src/Icon/asset/oakd_IconMoon.svg\"){kind=icon}
**Dark Mode Support**\n\nAutomatically adapts to dark mode using:\n\n```css\n@media (prefers-color-scheme: dark) { ... }\n```\n\nCustomization options are in [`src/index.css`](src/index.css).\n\n### ![\"\"](\"src/Icon/asset/oakd_IconPaintBucket.svg\"){kind=icon}
**CSS Preprocessor Support**\n\nSupports **Sass, Less, Stylus** via:\n\n```sh\nyarn add node-sass --dev # Sass\nyarn add stylus --dev # Stylus\nyarn add less --dev # Less\n```\n\nFor **CSS Modules**, update `rollup-config.js`:\n\n```js\npostcss({\n modules: true,\n});\n```\n\n### **Styled Components**\n\nSee [this branch](https://github.com/HarveyD/react-component-library/tree/styled-components) for implementation.\n\n### ![\"\"](\"src/Icon/asset/oakd_IconFolder.svg\"){kind=icon}
**Code Splitting**\n\nLoad components on demand:\n\n```tsx\nimport TestComponent from \"oakd/build/TestComponent\";\n```\n\nFor setup, refer to [this commit](https://github.com/HarveyD/react-component-library/commit/94631be5a871f3b39dbc3e9bd3e75a8ae5b3b759).\n\n### ![\"\"](\"src/Icon/asset/oakd_IconPicture.svg\"){kind=icon}
**Image Importing**\n\nImage imports **now work automatically** without additional configuration. You can use:\n\n```tsx\nimport logo from \"./logo.png\";\nexport const ImageComponent = () => ![\"\"](\"src/Icon/asset/oakd_IconScroll.svg\"){kind=icon}
**JSON Importing**\n\nInstall JSON plugin:\n\n```sh\nnpm i -D @rollup/plugin-json\n```\n\nAdd it to `rollup-config.js`:\n\n```js\nplugins: [json(), ...]\n```\n\nNow you can import JSON files:\n\n```tsx\nimport data from \"./some-data.json\";\nexport const JsonDataComponent = () => {data.description}
;\n```\n\n---\n\n## **Resources & Links**\n\n- [Storybook Docs](https://storybook.js.org/)\n- ![\"\"](\"src/Icon/asset/oakd_IconLightning.svg\"){kind=icon}
[Rollup Plugins](https://github.com/rollup/plugins)\n- [CSS Variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties)\n- [Styled Components](https://styled-components.com/)\n\n---\n\n## ![\"\"](\"src/Icon/asset/oakd_IconHandPeace.svg\"){kind=icon}
**Contributing**\n\nWe welcome contributions! Open an issue or submit a PR to improve `oakd`. \nFor detailed contribution guidelines, refer to our **[Contributing Guide](CONTRIBUTING.md)**.\n\n---\n\n### ![\"\"](\"src/Icon/asset/oakd_IconComment.svg\"){kind=icon}
**Join the Discussion**\n\nHave questions or ideas? Feel free to reach out on GitHub Discussions or open an issue!\n","readmeFilename":"README.md"}