@foi/design-system 0.0.19 → 0.0.21

package/README.md

@@ -44,6 +44,7 @@ npm publish --access public
 
 | Component     | Description                                                                                |
 | ------------- | ------------------------------------------------------------------------------------------ |
+| `Badge`       | Notification indicator that wraps any element — shows a count, overflow cap, or dot        |
 | `Button`      | Primary action button with variant/size/color support                                      |
 | `Checkbox`    | Single checkbox — standalone, RHF, or inside a group                                       |
 | `Chip`        | Compact inline label for statuses and tags — themed variants, accepts text or ReactNode    |
@@ -83,9 +84,7 @@ All field components share the same integration pattern. Define a Zod schema, pa
 import { useForm } from 'react-hook-form';
 import { zodResolver } from '@hookform/resolvers/zod';
 import { z } from 'zod';
-import TextField from '@components/atoms/TextField';
-import NumberField from '@components/atoms/NumberField';
-import Button from '@components/atoms/Button';
+import { TextField, NumberField, Button } from '@foi/design-system';
 
 const schema = z.object({
   email: z.string().email('Invalid email'),
@@ -164,8 +163,7 @@ A text input field with a floating label, helper text, and full error state inte
 ### Example
 
 ```tsx
-import TextField from '@components/atoms/TextField';
-import Icon from '@components/atoms/Icon';
+import { TextField, Icon } from '@foi/design-system';
 
 <TextField
   name='email'
@@ -209,7 +207,7 @@ All `TextField` props apply except `type`, `endAdornment`, and `startAdornment`
 ### Example
 
 ```tsx
-import NumberField from '@components/atoms/NumberField';
+import { NumberField } from '@foi/design-system';
 
 // Standard — quantity picker with bounds
 <NumberField
@@ -237,8 +235,8 @@ import NumberField from '@components/atoms/NumberField';
 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 darkTheme from './themes/dark';
+import { ThemeProvider } from '@foi/design-system';
+import { darkTheme } from '@foi/design-system/theme';
 
 <ThemeProvider themes={[darkTheme]} theme='dark'>
   <App />
@@ -254,32 +252,32 @@ Each variant contains:
 - `ROOT` — static styles applied unconditionally (e.g. `border-radius`, `background-color`)
 - `EVENTS` — styles scoped to interaction states. The complete set of possible states is:
 
-| State | Description |
-| --- | --- |
-| `ENABLED` | Default resting state — element is interactive and fully visible |
-| `VALUE` | The filled or selected part of the element (e.g. track fill, typed text colour) |
-| `HOVER` | While the pointer is over the element |
-| `ACTIVE` | While the element is being pressed |
-| `FOCUS` | When the element has keyboard focus |
-| `ERROR` | Container styles when validation fails |
-| `ERROR_VALUE` | Value part when in error state |
-| `ERROR_HOVER` | Hover while in error state |
-| `ERROR_ACTIVE` | Press while in error state |
-| `ERROR_FOCUS` | Focus while in error state |
-| `DISABLED` | When the element is not interactive |
-| `DISABLED_VALUE` | Value part when disabled |
-| `LOADING` | During a pending async operation |
-| `LOADING_VALUE` | Value part during loading |
+| State            | Description                                                                     |
+| ---------------- | ------------------------------------------------------------------------------- |
+| `ENABLED`        | Default resting state — element is interactive and fully visible                |
+| `VALUE`          | The filled or selected part of the element (e.g. track fill, typed text colour) |
+| `HOVER`          | While the pointer is over the element                                           |
+| `ACTIVE`         | While the element is being pressed                                              |
+| `FOCUS`          | When the element has keyboard focus                                             |
+| `ERROR`          | Container styles when validation fails                                          |
+| `ERROR_VALUE`    | Value part when in error state                                                  |
+| `ERROR_HOVER`    | Hover while in error state                                                      |
+| `ERROR_ACTIVE`   | Press while in error state                                                      |
+| `ERROR_FOCUS`    | Focus while in error state                                                      |
+| `DISABLED`       | When the element is not interactive                                             |
+| `DISABLED_VALUE` | Value part when disabled                                                        |
+| `LOADING`        | During a pending async operation                                                |
+| `LOADING_VALUE`  | Value part during loading                                                       |
 
 Not every component uses all states — each component defines only the states relevant to its interaction model. The TypeScript type exported from the component's theme file tells you exactly which states are available:
 
 ```ts
-import type { EVENTS } from '@hocs/ThemeProvider/components/atoms/Button';
-// Autocomplete will show only the states Button actually supports
+import type { BUTTON } from '@foi/design-system/theme';
+// BUTTON includes the EVENTS type — autocomplete shows only the states Button supports
 ```
 
 ```ts
-import type { BUTTON } from '@hocs/ThemeProvider/components/atoms/Button';
+import type { BUTTON } from '@foi/design-system/theme';
 
 const component = {
   BUTTON: {
@@ -347,8 +345,8 @@ An async data table that delegates all data operations to the server via `onFetc
 ### Defining columns
 
 ```tsx
-import DataGrid from '@components/organisms/DataGrid';
-import type { DataGridColumn } from '@components/organisms/DataGrid';
+import { DataGrid } from '@foi/design-system';
+import type { DataGridColumn } from '@foi/design-system';
 
 interface Product {
   id: number;
@@ -375,7 +373,7 @@ const columns: DataGridColumn<Product>[] = [
 `label` accepts any `ReactNode`. A plain string is automatically wrapped in the themed `--DATAGRID-thLabel` span so it inherits the header typography. Pass a custom node to render icons, badges, or anything else without that wrapper:
 
 ```tsx
-import Icon from '@components/atoms/Icon';
+import { Icon } from '@foi/design-system';
 
 {
   key: 'price',
@@ -441,9 +439,7 @@ A portal-based overlay dialog. Renders into `document.body` so it sits above all
 ### Basic usage
 
 ```tsx
-import Modal from '@components/molecules/Modal';
-import Button from '@components/atoms/Button';
-import Icon from '@components/atoms/Icon';
+import { Modal, Button, Icon } from '@foi/design-system';
 
 const [open, setOpen] = useState(false);
 
@@ -493,29 +489,86 @@ Apply `--MODAL-title` to the title element inside `header` to receive the themed
 | Backdrop click | ✓                      | —                     |
 | Escape key     | ✓                      | —                     |
 
+## Badge
+
+Wraps any element and overlays a small indicator at one of its corners. Renders a numeric count, a capped overflow label (`max+`), or a plain dot.
+
+### Props
+
+| Prop       | Type                                                           | Default       | Description                                       |
+| ---------- | -------------------------------------------------------------- | ------------- | ------------------------------------------------- |
+| `children` | `ReactNode`                                                    | —             | Element to wrap                                   |
+| `count`    | `number`                                                       | —             | Number to display; hidden when `0` or `undefined` |
+| `max`      | `number`                                                       | —             | Cap value — shows `max+` when `count` exceeds it  |
+| `dot`      | `boolean`                                                      | `false`       | Show a small dot instead of a number              |
+| `position` | `'top-right' \| 'top-left' \| 'bottom-right' \| 'bottom-left'` | `'top-right'` | Corner where the indicator is placed              |
+| `variant`  | `string`                                                       | `'default'`   | Theme variant                                     |
+| `theme`    | `EVENTS`                                                       | —             | One-off token override                            |
+
+The indicator animates in with a spring-scale effect on mount. The animation direction adapts automatically to the chosen `position`.
+
+### Example
+
+```tsx
+import { Badge, IconButton, Icon } from '@foi/design-system';
+
+// Count
+<Badge count={5}>
+  <IconButton icon={<Icon name='notifications' />} onClick={openNotifications} />
+</Badge>
+
+// Overflow cap — displays "999+"
+<Badge count={1200} max={999}>
+  <IconButton icon={<Icon name='mail' />} onClick={openMail} />
+</Badge>
+
+// Dot — no number
+<Badge dot position='bottom-right'>
+  <IconButton icon={<Icon name='settings' />} onClick={openSettings} />
+</Badge>
+```
+
+### Theming
+
+```ts
+import type { BADGE } from '@foi/design-system/theme';
+
+const badge = {
+  BADGE: {
+    DEFAULT: {
+      EVENTS: {
+        ENABLED: {
+          'background-color': '#ef4444',
+          'color-primary': '#ffffff',
+        },
+      },
+    },
+  },
+} as const satisfies BADGE;
+```
+
 ## Button
 
 The primary interactive element. Accepts any `ReactNode` as children and natively supports all standard `<button>` HTML attributes.
 
 ### Props
 
-| Prop        | Type                   | Default     | Description                                              |
-| ----------- | ---------------------- | ----------- | -------------------------------------------------------- |
-| `children`  | `ReactNode`            | —           | Button label or content                                  |
-| `type`      | `'button' \| 'submit'` | `'button'`  | HTML button type                                         |
-| `iconStart` | `JSX.Element`          | —           | Icon rendered before the label                           |
-| `iconEnd`   | `JSX.Element`          | —           | Icon rendered after the label                            |
-| `loading`   | `boolean`              | `false`     | Shows a loading indicator; button stays mounted          |
-| `disabled`  | `boolean`              | `false`     | Prevents interaction                                     |
-| `className` | `string`               | —           | Extra CSS class                                          |
-| `variant`   | `string`               | `'default'` | Theme variant                                            |
-| `theme`     | `EVENTS`               | —           | One-off token override                                   |
+| Prop        | Type                   | Default     | Description                                     |
+| ----------- | ---------------------- | ----------- | ----------------------------------------------- |
+| `children`  | `ReactNode`            | —           | Button label or content                         |
+| `type`      | `'button' \| 'submit'` | `'button'`  | HTML button type                                |
+| `iconStart` | `JSX.Element`          | —           | Icon rendered before the label                  |
+| `iconEnd`   | `JSX.Element`          | —           | Icon rendered after the label                   |
+| `loading`   | `boolean`              | `false`     | Shows a loading indicator; button stays mounted |
+| `disabled`  | `boolean`              | `false`     | Prevents interaction                            |
+| `className` | `string`               | —           | Extra CSS class                                 |
+| `variant`   | `string`               | `'default'` | Theme variant                                   |
+| `theme`     | `EVENTS`               | —           | One-off token override                          |
 
 ### Example
 
 ```tsx
-import Button from '@components/atoms/Button';
-import Icon from '@components/atoms/Icon';
+import { Button, Icon } from '@foi/design-system';
 
 <Button onClick={handleSave}>Guardar</Button>
 <Button type='submit' iconStart={<Icon name='send' />}>Enviar</Button>
@@ -529,18 +582,18 @@ Renders a single icon from the [Material Symbols Rounded](https://fonts.google.c
 
 ### Props
 
-| Prop        | Type                          | Default  | Description                              |
-| ----------- | ----------------------------- | -------- | ---------------------------------------- |
-| `name`      | `string`                      | —        | Material Symbols ligature name           |
-| `fill`      | `boolean`                     | `false`  | Use the filled variant of the icon       |
-| `size`      | `'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` | Icon size                                |
-| `className` | `string`                      | —        | Extra CSS class                          |
-| `style`     | `CSSProperties`               | —        | Inline styles                            |
+| Prop        | Type                           | Default | Description                        |
+| ----------- | ------------------------------ | ------- | ---------------------------------- |
+| `name`      | `string`                       | —       | Material Symbols ligature name     |
+| `fill`      | `boolean`                      | `false` | Use the filled variant of the icon |
+| `size`      | `'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'`  | Icon size                          |
+| `className` | `string`                       | —       | Extra CSS class                    |
+| `style`     | `CSSProperties`                | —       | Inline styles                      |
 
 ### Example
 
 ```tsx
-import Icon from '@components/atoms/Icon';
+import { Icon } from '@foi/design-system';
 
 <Icon name='home' />
 <Icon name='search' size='lg' />
@@ -553,21 +606,20 @@ A button that renders a single icon with no visible text. Accepts all standard `
 
 ### Props
 
-| Prop        | Type          | Default     | Description                                            |
-| ----------- | ------------- | ----------- | ------------------------------------------------------ |
-| `icon`      | `JSX.Element` | —           | Icon element to render (use `<Icon />`)                |
-| `onClick`   | `function`    | —           | Click handler                                          |
-| `isFlipped` | `boolean`     | `false`     | Mirrors the icon horizontally (useful for arrows)      |
-| `disabled`  | `boolean`     | `false`     | Prevents interaction                                   |
-| `className` | `string`      | —           | Extra CSS class                                        |
-| `variant`   | `string`      | `'default'` | Theme variant                                          |
-| `theme`     | `EVENTS`      | —           | One-off token override                                 |
+| Prop        | Type          | Default     | Description                                       |
+| ----------- | ------------- | ----------- | ------------------------------------------------- |
+| `icon`      | `JSX.Element` | —           | Icon element to render (use `<Icon />`)           |
+| `onClick`   | `function`    | —           | Click handler                                     |
+| `isFlipped` | `boolean`     | `false`     | Mirrors the icon horizontally (useful for arrows) |
+| `disabled`  | `boolean`     | `false`     | Prevents interaction                              |
+| `className` | `string`      | —           | Extra CSS class                                   |
+| `variant`   | `string`      | `'default'` | Theme variant                                     |
+| `theme`     | `EVENTS`      | —           | One-off token override                            |
 
 ### Example
 
 ```tsx
-import IconButton from '@components/atoms/IconButton';
-import Icon from '@components/atoms/Icon';
+import { IconButton, Icon } from '@foi/design-system';
 
 <IconButton icon={<Icon name='close' />} onClick={() => setOpen(false)} />
 <IconButton icon={<Icon name='arrow_forward' />} isFlipped onClick={goBack} />
@@ -579,31 +631,31 @@ A single checkbox. Can be used standalone (controlled or RHF), or as a child of
 
 ### Props
 
-| Prop            | Type                      | Default     | Description                                           |
-| --------------- | ------------------------- | ----------- | ----------------------------------------------------- |
-| `name`          | `string`                  | —           | RHF field name (required in standalone RHF mode)      |
-| `control`       | `Control`                 | —           | RHF control object                                    |
-| `checked`       | `boolean`                 | —           | Controlled mode value (use with `onChecked`)          |
-| `onChecked`     | `(checked: boolean) => void` | —        | Controlled mode change handler                        |
-| `label`         | `string`                  | —           | Text label next to the checkbox                       |
-| `icon`          | `JSX.Element`             | checkmark   | Custom icon shown when checked                        |
-| `disabled`      | `boolean`                 | `false`     | Prevents interaction                                  |
-| `helperText`    | `string`                  | —           | Hint text below the checkbox                          |
-| `showErrorText` | `boolean`                 | `true`      | Show validation error message                         |
-| `variant`       | `string`                  | `'default'` | Theme variant                                         |
-| `theme`         | `EVENTS`                  | —           | One-off token override                                |
+| Prop            | Type                         | Default     | Description                                      |
+| --------------- | ---------------------------- | ----------- | ------------------------------------------------ |
+| `name`          | `string`                     | —           | RHF field name (required in standalone RHF mode) |
+| `control`       | `Control`                    | —           | RHF control object                               |
+| `checked`       | `boolean`                    | —           | Controlled mode value (use with `onChecked`)     |
+| `onChecked`     | `(checked: boolean) => void` | —           | Controlled mode change handler                   |
+| `label`         | `string`                     | —           | Text label next to the checkbox                  |
+| `icon`          | `JSX.Element`                | checkmark   | Custom icon shown when checked                   |
+| `disabled`      | `boolean`                    | `false`     | Prevents interaction                             |
+| `helperText`    | `string`                     | —           | Hint text below the checkbox                     |
+| `showErrorText` | `boolean`                    | `true`      | Show validation error message                    |
+| `variant`       | `string`                     | `'default'` | Theme variant                                    |
+| `theme`         | `EVENTS`                     | —           | One-off token override                           |
 
 ### Example
 
 ```tsx
-import Checkbox from '@components/atoms/Checkbox';
+import { Checkbox } from '@foi/design-system';
 
 // RHF
-<Checkbox name='agree' control={control} label='Acepto los términos' />
+<Checkbox name='agree' control={control} label='Acepto los términos' />;
 
 // Controlled
 const [checked, setChecked] = useState(false);
-<Checkbox checked={checked} onChecked={setChecked} label='Recordarme' />
+<Checkbox checked={checked} onChecked={setChecked} label='Recordarme' />;
 ```
 
 ## Radio
@@ -612,14 +664,14 @@ A single radio button. Always used inside `RadioGroup` — it receives its state
 
 ### Props
 
-| Prop        | Type          | Default     | Description                                      |
-| ----------- | ------------- | ----------- | ------------------------------------------------ |
-| `value`     | `string`      | —           | The value this option represents                 |
-| `label`     | `string`      | —           | Text label next to the radio                     |
-| `icon`      | `JSX.Element` | filled dot  | Custom icon shown when selected                  |
-| `disabled`  | `boolean`     | `false`     | Overrides the group `disabled` for this item     |
-| `variant`   | `string`      | `'default'` | Theme variant                                    |
-| `theme`     | `EVENTS`      | —           | One-off token override                           |
+| Prop       | Type          | Default     | Description                                  |
+| ---------- | ------------- | ----------- | -------------------------------------------- |
+| `value`    | `string`      | —           | The value this option represents             |
+| `label`    | `string`      | —           | Text label next to the radio                 |
+| `icon`     | `JSX.Element` | filled dot  | Custom icon shown when selected              |
+| `disabled` | `boolean`     | `false`     | Overrides the group `disabled` for this item |
+| `variant`  | `string`      | `'default'` | Theme variant                                |
+| `theme`    | `EVENTS`      | —           | One-off token override                       |
 
 ## Select
 
@@ -627,34 +679,34 @@ A dropdown select field backed by a virtual-scroll list. Integrates with RHF and
 
 ### Props
 
-| Prop               | Type            | Default     | Description                                               |
-| ------------------ | --------------- | ----------- | --------------------------------------------------------- |
-| `name`             | `string`        | —           | RHF field name                                            |
-| `label`            | `string`        | —           | Floating label                                            |
-| `control`          | `Control`       | —           | RHF control object                                        |
-| `options`          | `OptionProp[]`  | —           | List of `{ value, label, description? }` items            |
-| `disabled`         | `boolean`       | `false`     | Prevents interaction                                      |
-| `range`            | `number`        | `100`       | Options per page (virtual scroll activates above 3)       |
-| `hasSearch`        | `boolean`       | `false`     | Shows a search input — filters after 3 characters        |
-| `hasDescription`   | `boolean`       | `false`     | Renders a secondary description line per option           |
-| `hasStaticOptions` | `boolean`       | `false`     | Renders dropdown inline (no absolute positioning)         |
-| `helperText`       | `string`        | —           | Hint text below the field                                 |
-| `showErrorText`    | `boolean`       | `true`      | Show validation error message                             |
-| `hasPadding`       | `boolean`       | `false`     | Add bottom padding for helper/error text                  |
-| `variant`          | `string`        | `'default'` | Theme variant                                             |
-| `theme`            | `EVENTS`        | —           | One-off token override                                    |
+| Prop               | Type           | Default     | Description                                         |
+| ------------------ | -------------- | ----------- | --------------------------------------------------- |
+| `name`             | `string`       | —           | RHF field name                                      |
+| `label`            | `string`       | —           | Floating label                                      |
+| `control`          | `Control`      | —           | RHF control object                                  |
+| `options`          | `OptionProp[]` | —           | List of `{ value, label, description? }` items      |
+| `disabled`         | `boolean`      | `false`     | Prevents interaction                                |
+| `range`            | `number`       | `100`       | Options per page (virtual scroll activates above 3) |
+| `hasSearch`        | `boolean`      | `false`     | Shows a search input — filters after 3 characters   |
+| `hasDescription`   | `boolean`      | `false`     | Renders a secondary description line per option     |
+| `hasStaticOptions` | `boolean`      | `false`     | Renders dropdown inline (no absolute positioning)   |
+| `helperText`       | `string`       | —           | Hint text below the field                           |
+| `showErrorText`    | `boolean`      | `true`      | Show validation error message                       |
+| `hasPadding`       | `boolean`      | `false`     | Add bottom padding for helper/error text            |
+| `variant`          | `string`       | `'default'` | Theme variant                                       |
+| `theme`            | `EVENTS`       | —           | One-off token override                              |
 
 ### Example
 
 ```tsx
-import Select from '@components/atoms/Select';
+import { Select } from '@foi/design-system';
 
 const options = [
   { value: 'cl', label: 'Chile' },
   { value: 'ar', label: 'Argentina', description: 'Buenos Aires' },
 ];
 
-<Select name='country' control={control} label='País' options={options} hasSearch />
+<Select name='country' control={control} label='País' options={options} hasSearch />;
 ```
 
 ## DatePicker
@@ -663,28 +715,28 @@ A date input field with an inline or floating calendar. Stores a `Date` value in
 
 ### Props
 
-| Prop               | Type             | Default     | Description                                              |
-| ------------------ | ---------------- | ----------- | -------------------------------------------------------- |
-| `name`             | `string`         | —           | RHF field name                                           |
-| `label`            | `string`         | —           | Floating label                                           |
-| `control`          | `Control`        | —           | RHF control object                                       |
-| `language`         | `'es' \| 'en'`   | browser     | Date format and labels (`DD/MM/YYYY` vs `MM/DD/YYYY`)    |
-| `minDate`          | `Date`           | —           | Earliest selectable date                                 |
-| `maxDate`          | `Date`           | —           | Latest selectable date                                   |
-| `disablePast`      | `boolean`        | `false`     | Disables all dates before today                          |
-| `disableFuture`    | `boolean`        | `false`     | Disables all dates after today                           |
-| `hasStaticOptions` | `boolean`        | `false`     | Renders calendar inline instead of floating              |
-| `disabled`         | `boolean`        | `false`     | Prevents interaction                                     |
-| `helperText`       | `string`         | —           | Hint text below the field                                |
-| `showErrorText`    | `boolean`        | `true`      | Show validation error message                            |
-| `hasPadding`       | `boolean`        | `false`     | Add bottom padding for helper/error text                 |
-| `variant`          | `string`         | `'default'` | Theme variant                                            |
-| `theme`            | `EVENTS`         | —           | One-off token override                                   |
+| Prop               | Type           | Default     | Description                                           |
+| ------------------ | -------------- | ----------- | ----------------------------------------------------- |
+| `name`             | `string`       | —           | RHF field name                                        |
+| `label`            | `string`       | —           | Floating label                                        |
+| `control`          | `Control`      | —           | RHF control object                                    |
+| `language`         | `'es' \| 'en'` | browser     | Date format and labels (`DD/MM/YYYY` vs `MM/DD/YYYY`) |
+| `minDate`          | `Date`         | —           | Earliest selectable date                              |
+| `maxDate`          | `Date`         | —           | Latest selectable date                                |
+| `disablePast`      | `boolean`      | `false`     | Disables all dates before today                       |
+| `disableFuture`    | `boolean`      | `false`     | Disables all dates after today                        |
+| `hasStaticOptions` | `boolean`      | `false`     | Renders calendar inline instead of floating           |
+| `disabled`         | `boolean`      | `false`     | Prevents interaction                                  |
+| `helperText`       | `string`       | —           | Hint text below the field                             |
+| `showErrorText`    | `boolean`      | `true`      | Show validation error message                         |
+| `hasPadding`       | `boolean`      | `false`     | Add bottom padding for helper/error text              |
+| `variant`          | `string`       | `'default'` | Theme variant                                         |
+| `theme`            | `EVENTS`       | —           | One-off token override                                |
 
 ### Example
 
 ```tsx
-import DatePicker from '@components/atoms/DatePicker';
+import { DatePicker } from '@foi/design-system';
 
 <DatePicker
   name='birthDate'
@@ -693,7 +745,7 @@ import DatePicker from '@components/atoms/DatePicker';
   language='es'
   disableFuture
   maxDate={new Date('2005-01-01')}
-/>
+/>;
 ```
 
 ## Switch
@@ -702,23 +754,22 @@ A toggle switch that stores a `boolean` value in RHF.
 
 ### Props
 
-| Prop        | Type       | Default     | Description                                 |
-| ----------- | ---------- | ----------- | ------------------------------------------- |
-| `name`      | `string`   | —           | RHF field name                              |
-| `control`   | `Control`  | —           | RHF control object                          |
-| `label`     | `string`   | —           | Text label next to the switch               |
-| `iconOn`    | `JSX.Element` | —        | Icon on the thumb when on                   |
-| `iconOff`   | `JSX.Element` | —        | Icon on the thumb when off                  |
-| `disabled`  | `boolean`  | `false`     | Prevents interaction                        |
-| `helperText`| `string`   | —           | Hint text below the switch                  |
-| `variant`   | `string`   | `'default'` | Theme variant                               |
-| `theme`     | `EVENTS`   | —           | One-off token override                      |
+| Prop         | Type          | Default     | Description                   |
+| ------------ | ------------- | ----------- | ----------------------------- |
+| `name`       | `string`      | —           | RHF field name                |
+| `control`    | `Control`     | —           | RHF control object            |
+| `label`      | `string`      | —           | Text label next to the switch |
+| `iconOn`     | `JSX.Element` | —           | Icon on the thumb when on     |
+| `iconOff`    | `JSX.Element` | —           | Icon on the thumb when off    |
+| `disabled`   | `boolean`     | `false`     | Prevents interaction          |
+| `helperText` | `string`      | —           | Hint text below the switch    |
+| `variant`    | `string`      | `'default'` | Theme variant                 |
+| `theme`      | `EVENTS`      | —           | One-off token override        |
 
 ### Example
 
 ```tsx
-import Switch from '@components/atoms/Switch';
-import Icon from '@components/atoms/Icon';
+import { Switch, Icon } from '@foi/design-system';
 
 <Switch
   name='notifications'
@@ -726,7 +777,7 @@ import Icon from '@components/atoms/Icon';
   label='Activar notificaciones'
   iconOn={<Icon name='notifications' />}
   iconOff={<Icon name='notifications_off' />}
-/>
+/>;
 ```
 
 ## Slider
@@ -735,28 +786,28 @@ A range slider that stores a `number[]` value in RHF. Single-thumb mode uses a 1
 
 ### Props
 
-| Prop         | Type                            | Default        | Description                                            |
-| ------------ | ------------------------------- | -------------- | ------------------------------------------------------ |
-| `name`       | `string`                        | —              | RHF field name                                         |
-| `control`    | `Control`                       | —              | RHF control object                                     |
-| `min`        | `number`                        | —              | Minimum value                                          |
-| `max`        | `number`                        | —              | Maximum value (`Infinity` disables click-to-seek)      |
-| `step`       | `number`                        | `1`            | Snap granularity                                       |
-| `distance`   | `number`                        | `0`            | Minimum gap between thumbs (range mode only)           |
-| `direction`  | `'horizontal' \| 'vertical'`    | `'horizontal'` | Slider orientation                                     |
-| `track`      | `'normal' \| 'inverted'`        | `'normal'`     | Fill direction of the track                            |
-| `showMarks`  | `boolean`                       | `false`        | Show a dot at every `step` position                    |
-| `iconMin`    | `JSX.Element`                   | —              | Icon inside the min/single thumb                       |
-| `iconMax`    | `JSX.Element`                   | —              | Icon inside the max thumb (range mode only)            |
-| `helperText` | `string`                        | —              | Hint text below the slider                             |
-| `disabled`   | `boolean`                       | `false`        | Prevents interaction                                   |
-| `variant`    | `string`                        | `'default'`    | Theme variant                                          |
-| `theme`      | `EVENTS`                        | —              | One-off token override                                 |
+| Prop         | Type                         | Default        | Description                                       |
+| ------------ | ---------------------------- | -------------- | ------------------------------------------------- |
+| `name`       | `string`                     | —              | RHF field name                                    |
+| `control`    | `Control`                    | —              | RHF control object                                |
+| `min`        | `number`                     | —              | Minimum value                                     |
+| `max`        | `number`                     | —              | Maximum value (`Infinity` disables click-to-seek) |
+| `step`       | `number`                     | `1`            | Snap granularity                                  |
+| `distance`   | `number`                     | `0`            | Minimum gap between thumbs (range mode only)      |
+| `direction`  | `'horizontal' \| 'vertical'` | `'horizontal'` | Slider orientation                                |
+| `track`      | `'normal' \| 'inverted'`     | `'normal'`     | Fill direction of the track                       |
+| `showMarks`  | `boolean`                    | `false`        | Show a dot at every `step` position               |
+| `iconMin`    | `JSX.Element`                | —              | Icon inside the min/single thumb                  |
+| `iconMax`    | `JSX.Element`                | —              | Icon inside the max thumb (range mode only)       |
+| `helperText` | `string`                     | —              | Hint text below the slider                        |
+| `disabled`   | `boolean`                    | `false`        | Prevents interaction                              |
+| `variant`    | `string`                     | `'default'`    | Theme variant                                     |
+| `theme`      | `EVENTS`                     | —              | One-off token override                            |
 
 ### Example
 
 ```tsx
-import Slider from '@components/atoms/Slider';
+import { Slider } from '@foi/design-system';
 
 // Single thumb — value is [number]
 <Slider name='volume' control={control} min={0} max={100} />
@@ -771,23 +822,27 @@ An animated placeholder rendered while content is loading. Has no logic — simp
 
 ### Props
 
-| Prop        | Type                              | Default          | Description                      |
-| ----------- | --------------------------------- | ---------------- | -------------------------------- |
-| `variant`   | `'rectangular' \| 'circular'`     | `'rectangular'`  | Shape of the placeholder         |
-| `width`     | `string \| number`                | —                | CSS width or pixel number        |
-| `height`    | `string \| number`                | —                | CSS height or pixel number       |
-| `className` | `string`                          | —                | Extra CSS class                  |
+| Prop        | Type                          | Default         | Description                |
+| ----------- | ----------------------------- | --------------- | -------------------------- |
+| `variant`   | `'rectangular' \| 'circular'` | `'rectangular'` | Shape of the placeholder   |
+| `width`     | `string \| number`            | —               | CSS width or pixel number  |
+| `height`    | `string \| number`            | —               | CSS height or pixel number |
+| `className` | `string`                      | —               | Extra CSS class            |
 
 ### Example
 
 ```tsx
-import Skeleton from '@components/atoms/Skeleton';
+import { Skeleton } from '@foi/design-system';
 
 // While loading a user avatar
-{isLoading ? <Skeleton variant='circular' width={40} height={40} /> : <Avatar src={user.photo} />}
+{
+  isLoading ? <Skeleton variant='circular' width={40} height={40} /> : <Avatar src={user.photo} />;
+}
 
 // While loading a text block
-{isLoading ? <Skeleton width='100%' height={20} /> : <p>{content}</p>}
+{
+  isLoading ? <Skeleton width='100%' height={20} /> : <p>{content}</p>;
+}
 ```
 
 ## Pagination
@@ -796,20 +851,20 @@ A standalone page-navigation bar. `DataGrid` uses this internally, but it can al
 
 ### Props
 
-| Prop               | Type               | Default | Description                                         |
-| ------------------ | ------------------ | ------- | --------------------------------------------------- |
-| `page`             | `number`           | —       | Zero-based current page index                       |
-| `total`            | `number`           | —       | Total row count (used to compute page count)        |
-| `pageSize`         | `number`           | —       | Rows per page                                       |
-| `onPageChange`     | `(page: number) => void` | — | Fired when the user navigates to a different page   |
-| `pageSizeOptions`  | `number[]`         | —       | Shows a rows-per-page selector with these options   |
-| `onPageSizeChange` | `(size: number) => void` | — | Fired when the user changes the page size           |
-| `loading`          | `boolean`          | `false` | Disables all controls while data is fetching        |
+| Prop               | Type                     | Default | Description                                       |
+| ------------------ | ------------------------ | ------- | ------------------------------------------------- |
+| `page`             | `number`                 | —       | Zero-based current page index                     |
+| `total`            | `number`                 | —       | Total row count (used to compute page count)      |
+| `pageSize`         | `number`                 | —       | Rows per page                                     |
+| `onPageChange`     | `(page: number) => void` | —       | Fired when the user navigates to a different page |
+| `pageSizeOptions`  | `number[]`               | —       | Shows a rows-per-page selector with these options |
+| `onPageSizeChange` | `(size: number) => void` | —       | Fired when the user changes the page size         |
+| `loading`          | `boolean`                | `false` | Disables all controls while data is fetching      |
 
 ### Example
 
 ```tsx
-import Pagination from '@components/atoms/Pagination';
+import { Pagination } from '@foi/design-system';
 
 <Pagination
   page={page}
@@ -818,7 +873,7 @@ import Pagination from '@components/atoms/Pagination';
   onPageChange={setPage}
   pageSizeOptions={[10, 25, 50]}
   onPageSizeChange={setPageSize}
-/>
+/>;
 ```
 
 ## CheckboxGroup
@@ -827,24 +882,23 @@ Manages a set of `Checkbox` children as a `string[]` RHF field. The group value
 
 ### Props
 
-| Prop            | Type                           | Default      | Description                                     |
-| --------------- | ------------------------------ | ------------ | ----------------------------------------------- |
-| `name`          | `string`                       | —            | RHF field name                                  |
-| `control`       | `Control`                      | —            | RHF control object                              |
-| `children`      | `ReactNode`                    | —            | `<Checkbox>` elements (each must have `value`)  |
-| `label`         | `string`                       | —            | Group label above the checkboxes                |
-| `direction`     | `'vertical' \| 'horizontal'`   | `'vertical'` | Layout direction of the items                   |
-| `disabled`      | `boolean`                      | `false`      | Disables all children                           |
-| `helperText`    | `string`                       | —            | Hint text below the group                       |
-| `showErrorText` | `boolean`                      | `true`       | Show validation error message                   |
-| `variant`       | `string`                       | `'default'`  | Theme variant                                   |
-| `theme`         | `EVENTS`                       | —            | One-off token override                          |
+| Prop            | Type                         | Default      | Description                                    |
+| --------------- | ---------------------------- | ------------ | ---------------------------------------------- |
+| `name`          | `string`                     | —            | RHF field name                                 |
+| `control`       | `Control`                    | —            | RHF control object                             |
+| `children`      | `ReactNode`                  | —            | `<Checkbox>` elements (each must have `value`) |
+| `label`         | `string`                     | —            | Group label above the checkboxes               |
+| `direction`     | `'vertical' \| 'horizontal'` | `'vertical'` | Layout direction of the items                  |
+| `disabled`      | `boolean`                    | `false`      | Disables all children                          |
+| `helperText`    | `string`                     | —            | Hint text below the group                      |
+| `showErrorText` | `boolean`                    | `true`       | Show validation error message                  |
+| `variant`       | `string`                     | `'default'`  | Theme variant                                  |
+| `theme`         | `EVENTS`                     | —            | One-off token override                         |
 
 ### Example
 
 ```tsx
-import CheckboxGroup from '@components/molecules/CheckboxGroup';
-import Checkbox from '@components/atoms/Checkbox';
+import { CheckboxGroup, Checkbox } from '@foi/design-system';
 
 const schema = z.object({
   skills: z.array(z.string()).min(1, 'Selecciona al menos una'),
@@ -854,7 +908,7 @@ const schema = z.object({
   <Checkbox value='react' label='React' />
   <Checkbox value='vue' label='Vue' />
   <Checkbox value='svelte' label='Svelte' />
-</CheckboxGroup>
+</CheckboxGroup>;
 ```
 
 ## CheckboxTree
@@ -863,31 +917,30 @@ A hierarchical checkbox group. The parent checkbox controls all children simulta
 
 ### Props
 
-| Prop                | Type          | Default          | Description                                          |
-| ------------------- | ------------- | ---------------- | ---------------------------------------------------- |
-| `name`              | `string`      | —                | RHF field name                                       |
-| `control`           | `Control`     | —                | RHF control object                                   |
-| `children`          | `ReactNode`   | —                | `<Checkbox>` elements (each must have `value`)       |
-| `label`             | `string`      | —                | Label on the parent (select-all) checkbox            |
-| `iconChecked`       | `JSX.Element` | checkmark        | Icon on the parent when all children are checked     |
-| `iconIndeterminate` | `JSX.Element` | dash             | Icon on the parent when some children are checked    |
-| `disabled`          | `boolean`     | `false`          | Disables the parent and all children                 |
-| `helperText`        | `string`      | —                | Hint text below the tree                             |
-| `showErrorText`     | `boolean`     | `true`           | Show validation error message                        |
-| `variant`           | `string`      | `'default'`      | Theme variant                                        |
-| `theme`             | `EVENTS`      | —                | One-off token override                               |
+| Prop                | Type          | Default     | Description                                       |
+| ------------------- | ------------- | ----------- | ------------------------------------------------- |
+| `name`              | `string`      | —           | RHF field name                                    |
+| `control`           | `Control`     | —           | RHF control object                                |
+| `children`          | `ReactNode`   | —           | `<Checkbox>` elements (each must have `value`)    |
+| `label`             | `string`      | —           | Label on the parent (select-all) checkbox         |
+| `iconChecked`       | `JSX.Element` | checkmark   | Icon on the parent when all children are checked  |
+| `iconIndeterminate` | `JSX.Element` | dash        | Icon on the parent when some children are checked |
+| `disabled`          | `boolean`     | `false`     | Disables the parent and all children              |
+| `helperText`        | `string`      | —           | Hint text below the tree                          |
+| `showErrorText`     | `boolean`     | `true`      | Show validation error message                     |
+| `variant`           | `string`      | `'default'` | Theme variant                                     |
+| `theme`             | `EVENTS`      | —           | One-off token override                            |
 
 ### Example
 
 ```tsx
-import CheckboxTree from '@components/molecules/CheckboxTree';
-import Checkbox from '@components/atoms/Checkbox';
+import { CheckboxTree, Checkbox } from '@foi/design-system';
 
 <CheckboxTree name='permissions' control={control} label='Seleccionar todo'>
   <Checkbox value='read' label='Leer' />
   <Checkbox value='write' label='Escribir' />
   <Checkbox value='delete' label='Eliminar' />
-</CheckboxTree>
+</CheckboxTree>;
 ```
 
 ## RadioGroup
@@ -896,24 +949,23 @@ Manages a set of `Radio` children as a single `string` RHF field. The value is t
 
 ### Props
 
-| Prop            | Type                           | Default      | Description                                    |
-| --------------- | ------------------------------ | ------------ | ---------------------------------------------- |
-| `name`          | `string`                       | —            | RHF field name                                 |
-| `control`       | `Control`                      | —            | RHF control object                             |
-| `children`      | `ReactNode`                    | —            | `<Radio>` elements (each must have `value`)    |
-| `label`         | `string`                       | —            | Group label above the radios                   |
-| `direction`     | `'vertical' \| 'horizontal'`   | `'vertical'` | Layout direction of the items                  |
-| `disabled`      | `boolean`                      | `false`      | Disables all children                          |
-| `helperText`    | `string`                       | —            | Hint text below the group                      |
-| `showErrorText` | `boolean`                      | `true`       | Show validation error message                  |
-| `variant`       | `string`                       | `'default'`  | Theme variant                                  |
-| `theme`         | `EVENTS`                       | —            | One-off token override                         |
+| Prop            | Type                         | Default      | Description                                 |
+| --------------- | ---------------------------- | ------------ | ------------------------------------------- |
+| `name`          | `string`                     | —            | RHF field name                              |
+| `control`       | `Control`                    | —            | RHF control object                          |
+| `children`      | `ReactNode`                  | —            | `<Radio>` elements (each must have `value`) |
+| `label`         | `string`                     | —            | Group label above the radios                |
+| `direction`     | `'vertical' \| 'horizontal'` | `'vertical'` | Layout direction of the items               |
+| `disabled`      | `boolean`                    | `false`      | Disables all children                       |
+| `helperText`    | `string`                     | —            | Hint text below the group                   |
+| `showErrorText` | `boolean`                    | `true`       | Show validation error message               |
+| `variant`       | `string`                     | `'default'`  | Theme variant                               |
+| `theme`         | `EVENTS`                     | —            | One-off token override                      |
 
 ### Example
 
 ```tsx
-import RadioGroup from '@components/molecules/RadioGroup';
-import Radio from '@components/atoms/Radio';
+import { RadioGroup, Radio } from '@foi/design-system';
 
 const schema = z.object({
   plan: z.string().min(1, 'Selecciona un plan'),
@@ -923,7 +975,7 @@ const schema = z.object({
   <Radio value='free' label='Gratis' />
   <Radio value='pro' label='Pro' />
   <Radio value='enterprise' label='Enterprise' />
-</RadioGroup>
+</RadioGroup>;
 ```
 
 ## Chip
@@ -932,19 +984,19 @@ A compact inline label for displaying statuses, tags, or categories. Height is f
 
 ### Props
 
-| Prop        | Type        | Default     | Description                                                   |
-| ----------- | ----------- | ----------- | ------------------------------------------------------------- |
-| `children`  | `ReactNode` | —           | Label text or custom content                                  |
-| `variant`   | `string`    | `'default'` | Theme variant — any key defined under `CHIP` in your theme    |
-| `className` | `string`    | —           | Extra CSS class                                               |
-| `theme`     | `EVENTS`    | —           | One-off token override                                        |
+| Prop        | Type        | Default     | Description                                                |
+| ----------- | ----------- | ----------- | ---------------------------------------------------------- |
+| `children`  | `ReactNode` | —           | Label text or custom content                               |
+| `variant`   | `string`    | `'default'` | Theme variant — any key defined under `CHIP` in your theme |
+| `className` | `string`    | —           | Extra CSS class                                            |
+| `theme`     | `EVENTS`    | —           | One-off token override                                     |
 
 When `children` is a plain string it is wrapped in a `span.--CHIP-label` that applies horizontal padding. Pass a `ReactNode` to render custom content (e.g. icon + text) directly inside the chip.
 
 ### Example
 
 ```tsx
-import Chip from '@components/atoms/Chip';
+import { Chip } from '@foi/design-system';
 
 // Plain string — wrapped in a padded span automatically
 <Chip>Activo</Chip>
@@ -974,7 +1026,7 @@ A notification system built around a React context. `ThemeProvider` automaticall
 ### `useToast`
 
 ```tsx
-import { useToast } from '@hooks';
+import { useToast } from '@foi/design-system/hooks';
 
 const { push } = useToast();
 
@@ -992,19 +1044,19 @@ push('Archivo guardado', { variant: 'success', icon: 'check_circle' });
 
 ### `ToastPosition`
 
-| Value             | Description  |
-| ----------------- | ------------ |
-| `'bottom-right'`  | Default      |
+| Value             | Description   |
+| ----------------- | ------------- |
+| `'bottom-right'`  | Default       |
 | `'bottom-center'` | Bottom center |
-| `'bottom-left'`   | Bottom left  |
-| `'top-right'`     | Top right    |
-| `'top-center'`    | Top center   |
-| `'top-left'`      | Top left     |
+| `'bottom-left'`   | Bottom left   |
+| `'top-right'`     | Top right     |
+| `'top-center'`    | Top center    |
+| `'top-left'`      | Top left      |
 
 ### Example
 
 ```tsx
-import { useToast } from '@hooks';
+import { useToast } from '@foi/design-system/hooks';
 
 const Notifier = () => {
   const { push } = useToast();
@@ -1027,7 +1079,7 @@ const Notifier = () => {
 Toast variants are defined in the theme under the `TOAST` key. Each variant must be self-contained (all tokens, not just overrides) because `useCreateComponentStyles` loads only the requested variant:
 
 ```ts
-import type { TOAST } from '@hocs/ThemeProvider/components/molecules/Toast';
+import type { TOAST } from '@foi/design-system/theme';
 
 const toast = {
   TOAST: {