@foi/design-system 0.0.10 → 0.0.12

package/README.md

@@ -4,17 +4,16 @@ A component library built with React 19 and TypeScript. Components are designed
 
 ## Tech stack
 
-| Tool | Version | Purpose |
-|---|---|---|
-| React | 19 | UI runtime |
-| TypeScript | 6 | Type safety |
-| Vite | 8 | Dev server & bundler |
-| Emotion | 11 | CSS-in-JS styling |
-| React Hook Form | 7 | Form state & validation |
-| Zod | 4 | Schema validation |
-| MUI Icons | 9 | Default icon set |
-| Storybook | 10 | Component explorer |
-| Vitest | 4 | Unit tests |
+| Tool            | Version | Purpose                 |
+| --------------- | ------- | ----------------------- |
+| React           | 19      | UI runtime              |
+| TypeScript      | 6       | Type safety             |
+| Vite            | 8       | Dev server & bundler    |
+| Emotion         | 11      | CSS-in-JS styling       |
+| React Hook Form | 7       | Form state & validation |
+| Zod             | 4       | Schema validation       |
+| Storybook       | 10      | Component explorer      |
+| Vitest          | 4       | Unit tests              |
 
 ## Commands
 
@@ -43,25 +42,26 @@ npm publish --access public
 
 ### Atoms
 
-| Component | Description |
-|---|---|
-| `Button` | Primary action button with variant/size/color support |
-| `Checkbox` | Single checkbox — standalone, RHF, or inside a group |
-| `DatePicker` | Date input with calendar menu, integrates with RHF |
-| `IconButton` | Clickable icon with button semantics |
-| `Input` | Text input field with label, helper text, and error state |
-| `Radio` | Single radio button — used inside `RadioGroup` |
-| `Select` | Dropdown select with RHF integration |
-| `Slider` | Range slider with RHF integration |
-| `Switch` | Toggle switch — boolean RHF field |
+| Component    | Description                                                         |
+| ------------ | ------------------------------------------------------------------- |
+| `Button`     | Primary action button with variant/size/color support               |
+| `Checkbox`   | Single checkbox — standalone, RHF, or inside a group                |
+| `DatePicker` | Date input with calendar menu, integrates with RHF                  |
+| `Icon`       | Font-based icon using Material Symbols Rounded — pass a `name` prop |
+| `IconButton` | Clickable icon with button semantics                                |
+| `Input`      | Text input field with label, helper text, and error state           |
+| `Radio`      | Single radio button — used inside `RadioGroup`                      |
+| `Select`     | Dropdown select with RHF integration                                |
+| `Slider`     | Range slider with RHF integration                                   |
+| `Switch`     | Toggle switch — boolean RHF field                                   |
 
 ### Molecules
 
-| Component | Description |
-|---|---|
+| Component       | Description                                                    |
+| --------------- | -------------------------------------------------------------- |
 | `CheckboxGroup` | Manages a set of `Checkbox` children as a `string[]` RHF field |
-| `CheckboxTree` | Hierarchical checkbox group with parent/child selection logic |
-| `RadioGroup` | Manages a set of `Radio` children as a single RHF field |
+| `CheckboxTree`  | Hierarchical checkbox group with parent/child selection logic  |
+| `RadioGroup`    | Manages a set of `Radio` children as a single RHF field        |
 
 ## Usage with React Hook Form
 
@@ -76,7 +76,7 @@ import Button from '@components/atoms/Button';
 
 const schema = z.object({
   email: z.string().email('Invalid email'),
-  age:   z.number().min(18, 'Must be 18 or older'),
+  age: z.number().min(18, 'Must be 18 or older'),
 });
 
 type FormValues = z.infer<typeof schema>;
@@ -88,9 +88,9 @@ const MyForm = () => {
 
   return (
     <form onSubmit={handleSubmit(console.log)}>
-      <Input name="email" control={control} label="Email" />
-      <Input name="age"   control={control} label="Age" type="number" />
-      <Button type="submit" label="Submit" />
+      <Input name='email' control={control} label='Email' />
+      <Input name='age' control={control} label='Age' type='number' />
+      <Button type='submit' label='Submit' />
     </form>
   );
 };
@@ -105,11 +105,11 @@ const schema = z.object({
   skills: z.array(z.string()).min(1, 'Select at least one'),
 });
 
-<CheckboxGroup name="skills" control={control} label="Skills">
-  <Checkbox value="react" label="React" />
-  <Checkbox value="vue"   label="Vue" />
-  <Checkbox value="svelte" label="Svelte" />
-</CheckboxGroup>
+<CheckboxGroup name='skills' control={control} label='Skills'>
+  <Checkbox value='react' label='React' />
+  <Checkbox value='vue' label='Vue' />
+  <Checkbox value='svelte' label='Svelte' />
+</CheckboxGroup>;
 ```
 
 ### Controlled mode (no RHF)
@@ -119,39 +119,92 @@ Pass `checked` + `onChecked` instead of `name`/`control`.
 ```tsx
 const [agreed, setAgreed] = useState(false);
 
-<Checkbox checked={agreed} onChecked={setAgreed} label="I agree to the terms" />
+<Checkbox checked={agreed} onChecked={setAgreed} label='I agree to the terms' />;
 ```
 
 ## Theming
 
-Wrap your app in `ThemeProvider` and define one or more themes. Each theme maps component tokens to CSS custom properties that components consume at render time.
+Wrap your app in `ThemeProvider` and pass one or more named themes. The active theme is selected by the `theme` prop and its tokens are injected as CSS custom properties that every component consumes.
 
 ```tsx
 import ThemeProvider from '@hocs/ThemeProvider';
-import { lightTheme, darkTheme } from './themes';
+import darkTheme from './themes/dark';
 
-<ThemeProvider themes={[lightTheme, darkTheme] as const} theme="light">
+<ThemeProvider themes={[darkTheme]} theme='dark'>
   <App />
-</ThemeProvider>
+</ThemeProvider>;
 ```
 
-A theme is a plain object with a `name`, a `fonts` map, and a `components` map:
+### Theme structure
+
+A theme is a plain object with a `name`, an optional `fonts` map, and a `components` map. Each component key holds one or more **variants**. Every component must define at least a `DEFAULT` variant; additional variants are optional.
+
+Each variant contains:
+
+- `ROOT` — static styles applied unconditionally (e.g. `border-radius`)
+- `EVENTS` — styles scoped to interaction states (`ENABLED`, `HOVER`, `FOCUS`, `ERROR`, `DISABLED`, etc.)
 
 ```ts
-const lightTheme = {
-  name: 'light',
-  fonts: { FONT_FAMILY: 'Inter, sans-serif' },
-  components: {
-    BUTTON: {
-      ROOT: { 'background-color': '#0070f3', color: '#fff' },
-      HOVER: { 'background-color': '#005bb5' },
+import type { BUTTON } from '@hocs/ThemeProvider/components/Button';
+
+const component = {
+  BUTTON: {
+    DEFAULT: {
+      ROOT: {
+        'border-radius': '8px',
+      },
+      EVENTS: {
+        ENABLED: {
+          'background-color': '#0070f3',
+          'color-primary': '#ffffff',
+        },
+        HOVER: {
+          'background-color': '#005bb5',
+        },
+        FOCUS: {
+          'outline-color': '#93c5fd',
+          'outline-width': '2px',
+          'outline-style': 'solid',
+          'outline-offset': '2px',
+        },
+        DISABLED: {
+          'background-color': '#e5e7eb',
+          'color-primary': '#9ca3af',
+        },
+      },
+    },
+    DANGER: {
+      EVENTS: {
+        ENABLED: {
+          'background-color': '#dc2626',
+          'color-primary': '#ffffff',
+        },
+        HOVER: {
+          'background-color': '#b91c1c',
+        },
+      },
     },
-    // ...other components
   },
-} satisfies Theme;
+} as const satisfies BUTTON;
+```
+
+The `satisfies BUTTON` check enforces that `DEFAULT` is present and that every token key is valid for that component. TypeScript reports an error at the theme file if a token is misspelled or if `DEFAULT` is missing.
+
+### Selecting a variant
+
+Pass the `variant` prop to a component to switch between the variants you defined in the theme. The default is always `'default'`.
+
+```tsx
+<Button label='Delete' variant='danger' />
 ```
 
-Individual components also accept a `theme` prop for one-off overrides without changing the global theme.
+### One-off theme override
+
+Any component also accepts a `theme` prop — a partial `EVENTS` object — to override tokens for that single instance without touching the global theme.
+
+```tsx
+<Button label='Special' theme={{ ENABLED: { 'background-color': '#7c3aed' } }} />
+```
 
 ## Project structure