@franco_roura/module-01 0.0.0-stage → 1.0.0

package/dist/tokens.css

@@ -0,0 +1,181 @@
+/* Module/01 tokens — generated from tokens/tokens.json by scripts/build-tokens.ts. Do not edit. */
+
+:root {
+  --color-graphite-50: #f3f4f6;
+  --color-graphite-100: #e7e9ec;
+  --color-graphite-200: #d8dadf;
+  --color-graphite-300: #c9ccd2;
+  --color-graphite-400: #a3a7ae;
+  --color-graphite-500: #7c818a;
+  --color-graphite-600: #676c74;
+  --color-graphite-700: #53575e;
+  --color-graphite-800: #36393e;
+  --color-graphite-900: #1c1e21;
+  --color-signal-50: #ffe9dd;
+  --color-signal-100: #ffd9c7;
+  --color-signal-200: #ffbda2;
+  --color-signal-300: #ffa17d;
+  --color-signal-400: #ff8255;
+  --color-signal-500: #ff5f1f;
+  --color-signal-600: #d94a12;
+  --color-signal-700: #b93d0a;
+  --color-signal-800: #8c2e08;
+  --color-signal-900: #612005;
+  --color-green-50: #dff2e5;
+  --color-green-100: #cdead5;
+  --color-green-200: #a8d9b6;
+  --color-green-300: #83c797;
+  --color-green-400: #59b679;
+  --color-green-500: #1fa45a;
+  --color-green-600: #1f8f55;
+  --color-green-700: #0f6e38;
+  --color-green-800: #0d552b;
+  --color-green-900: #093d1f;
+  --color-red-50: #feedeb;
+  --color-red-100: #fde4e1;
+  --color-red-200: #f8bfb5;
+  --color-red-300: #f19989;
+  --color-red-400: #e6715e;
+  --color-red-500: #d9442e;
+  --color-red-600: #c63423;
+  --color-red-700: #b42318;
+  --color-red-800: #8a1b12;
+  --color-red-900: #62120c;
+  --color-canvas: var(--color-graphite-50);
+  --color-shell: #ffffff;
+  --color-shell-recess: var(--color-graphite-100);
+  --color-seam: var(--color-graphite-300);
+  --color-ink: var(--color-graphite-900);
+  --color-ink-soft: var(--color-graphite-700);
+  --color-hud-mark: var(--color-graphite-500);
+  --color-signal: var(--color-signal-500);
+  --color-signal-ink: var(--color-signal-700);
+  --color-signal-shade: var(--color-signal-600);
+  --color-signal-tint: var(--color-signal-100);
+  --color-studio: #b9bccd;
+  --color-visor: var(--color-graphite-900);
+  --color-visor-mark: var(--color-graphite-400);
+  --color-glass: rgba(255,255,255,0.62);
+  --color-glass-edge: rgba(255,255,255,0.95);
+  --color-led-on: var(--color-green-500);
+  --color-income-ink: var(--color-green-700);
+  --color-expense-ink: var(--color-red-700);
+  --color-danger: var(--color-red-700);
+  --color-danger-tint: var(--color-red-100);
+  --color-overlay: rgba(28,30,33,0.36);
+  --color-cat-red: #f2706a;
+  --color-cat-orange: #ff8a4c;
+  --color-cat-amber: #f5b43a;
+  --color-cat-yellow: #f2d24b;
+  --color-cat-lime: #b5d65a;
+  --color-cat-green: #5cc98a;
+  --color-cat-teal: #4cc4b4;
+  --color-cat-cyan: #5cc6e0;
+  --color-cat-sky: #7fb8f5;
+  --color-cat-blue: #6f9ef2;
+  --color-cat-indigo: #8f95f0;
+  --color-cat-violet: #b08cf0;
+  --color-cat-pink: #f08cc8;
+  --color-cat-rose: #f58ca0;
+  --color-cat-brown: #c9a27a;
+  --color-cat-slate: #a3abb8;
+  --color-chart-income: var(--color-green-600);
+  --color-chart-expense: var(--color-red-500);
+  --color-chart-line: var(--color-signal-ink);
+  --font-display: var(--font-michroma, Michroma), "Eurostile", "Microgramma", system-ui, sans-serif;
+  --font-sans: var(--font-manrope, Manrope), system-ui, "Segoe UI", sans-serif;
+  --font-mono: var(--font-space-mono, "Space Mono"), ui-monospace, Menlo, Consolas, monospace;
+  --text-display-xl: 56px;
+  --text-display-xl--line-height: 1.1;
+  --text-display-xl--font-weight: 400;
+  --text-display-xl--letter-spacing: -0.01em;
+  --text-display-lg: 36px;
+  --text-display-lg--line-height: 1.15;
+  --text-display-lg--font-weight: 400;
+  --text-display-lg--letter-spacing: -0.01em;
+  --text-display-md: 24px;
+  --text-display-md--line-height: 1.25;
+  --text-display-md--font-weight: 400;
+  --text-display-md--letter-spacing: 0;
+  --text-display-sm: 17px;
+  --text-display-sm--line-height: 1.35;
+  --text-display-sm--font-weight: 400;
+  --text-display-sm--letter-spacing: 0.01em;
+  --text-body-lg: 19px;
+  --text-body-lg--line-height: 1.55;
+  --text-body-lg--font-weight: 400;
+  --text-body-lg--letter-spacing: 0;
+  --text-body-md: 16px;
+  --text-body-md--line-height: 1.6;
+  --text-body-md--font-weight: 400;
+  --text-body-md--letter-spacing: 0;
+  --text-body-sm: 14px;
+  --text-body-sm--line-height: 1.5;
+  --text-body-sm--font-weight: 400;
+  --text-body-sm--letter-spacing: 0;
+  --text-label: 14px;
+  --text-label--line-height: 1.2;
+  --text-label--font-weight: 700;
+  --text-label--letter-spacing: 0.01em;
+  --text-hud: 12px;
+  --text-hud--line-height: 1.3;
+  --text-hud--font-weight: 400;
+  --text-hud--letter-spacing: 0.12em;
+  --text-hud-sm: 10px;
+  --text-hud-sm--line-height: 1.2;
+  --text-hud-sm--font-weight: 400;
+  --text-hud-sm--letter-spacing: 0.16em;
+  --text-hud-num: 13px;
+  --text-hud-num--line-height: 1.3;
+  --text-hud-num--font-weight: 400;
+  --text-hud-num--letter-spacing: 0.04em;
+  --text-code: 14px;
+  --text-code--line-height: 1.6;
+  --text-code--font-weight: 400;
+  --text-code--letter-spacing: 0;
+  --text-amount-xl: 32px;
+  --text-amount-xl--line-height: 1.15;
+  --text-amount-xl--font-weight: 400;
+  --text-amount-xl--letter-spacing: -0.01em;
+  --text-amount-lg: 22px;
+  --text-amount-lg--line-height: 1.2;
+  --text-amount-lg--font-weight: 400;
+  --text-amount-lg--letter-spacing: 0;
+  --text-amount-md: 15px;
+  --text-amount-md--line-height: 1.3;
+  --text-amount-md--font-weight: 700;
+  --text-amount-md--letter-spacing: 0;
+  --radius-xs: 4px;
+  --radius-sm: 8px;
+  --radius-md: 14px;
+  --radius-lg: 24px;
+  --radius-xl: 36px;
+  --radius-full: 999px;
+  --shadow-mold: inset 0 1px 0 rgba(255,255,255,0.9), inset 0 -2px 0 rgba(28,30,33,0.06), 0 2px 4px rgba(28,30,33,0.06), 0 10px 24px rgba(28,30,33,0.08);
+  --shadow-press: inset 0 2px 5px rgba(28,30,33,0.16);
+  --shadow-float: 0 4px 10px rgba(28,30,33,0.06), 0 24px 48px rgba(28,30,33,0.10);
+  --shadow-glass: inset 0 0 0 1px rgba(255,255,255,0.95), 0 10px 30px rgba(28,30,33,0.10);
+  --container-content-max: 1120px;
+  --spacing-nav-height: 64px;
+  --spacing-control-height: 44px;
+  --container-sheet-max: 560px;
+}
+
+:root {
+  --space-1: 4px;
+  --space-2: 8px;
+  --space-3: 12px;
+  --space-4: 16px;
+  --space-6: 24px;
+  --space-8: 32px;
+  --space-12: 48px;
+  --space-16: 64px;
+  --space-24: 96px;
+  --filter-mold: drop-shadow(0 2px 4px rgba(28,30,33,0.06)) drop-shadow(0 10px 24px rgba(28,30,33,0.08));
+  --filter-press: ;
+  --filter-float: drop-shadow(0 4px 10px rgba(28,30,33,0.06)) drop-shadow(0 24px 48px rgba(28,30,33,0.10));
+  --filter-glass: drop-shadow(0 10px 30px rgba(28,30,33,0.10));
+  --notch-sm: 10px;
+  --notch-md: 20px;
+  --notch-lg: 36px;
+}

package/guidelines/AlertDialog.md

@@ -0,0 +1,9 @@
+# AlertDialog
+
+A modal that interrupts to confirm something that can't be undone, on Radix AlertDialog.
+
+Compose `AlertDialog`, `AlertDialogTrigger`, `AlertDialogContent` (`size`: `default` or `sm`), a header with `AlertDialogTitle` and `AlertDialogDescription`, and a footer with `AlertDialogCancel` and `AlertDialogAction`.
+
+- Only for destructive or irreversible actions. Everything else is a Dialog or needs no confirmation.
+- The title asks the question ("Delete this project?"); the description says what is lost.
+- The action repeats the verb ("Delete project") with `variant="destructive"`. Never "OK".

package/guidelines/Amount.md

@@ -0,0 +1,10 @@
+# Amount
+
+A money figure in tabular Space Mono, signed and colored by direction: `+1,234.56 USD`, `−42.05 USD`.
+
+Provide `minor` (an integer amount in minor units, as a BigInt), `currency` (ISO 4217) and `minorUnits` (decimal places). Optional `sign` (`always` default, `auto`, `never`), `code` (show the currency code, default true), `size` (`sm` = `hud-num`, `md` = `amount-md` default, `lg` = `amount-lg`, `xl` = `amount-xl`) and `tone` (`auto`, `plain` ink, `muted` ink-soft).
+
+- Positive is `income-ink`, negative `expense-ink`, zero `ink`. The sign is always printed, so color is never the only cue.
+- Negatives use a true minus (−), which lines up with + in mono.
+- Never format money from floats; amounts are integer minor units end to end.
+- Use `muted` for a secondary figure, like the other currency of a transfer.

package/guidelines/AppearancePickers.md

@@ -0,0 +1,8 @@
+# IconPicker and ColorPicker
+
+Swatch grids for choosing a category's glyph and palette color.
+
+Both take `value` and `onChange`. `IconPicker` offers the curated Lucide set; `ColorPicker` offers the sixteen `cat-*` colors.
+
+- They're native radio groups under the swatches, so arrow keys move the choice.
+- Show a CategoryIcon preview next to them so people see the pair together.

package/guidelines/Badge.md

@@ -0,0 +1,11 @@
+# Badge
+
+Stadium chip in HUD type for states and counts.
+
+Provide `children` (one or two words). Optional `variant`.
+
+- `default`: `shell-recess` fill, like a slot molded into the part.
+- `signal`: the one badge that matters most. `tint`: in-progress states. `outline`: quiet, on shell.
+- `secondary`: a raised `shell` chip with `shadow-mold`, for use on `canvas` or `shell-recess`.
+- `destructive`: `danger` text on `danger-tint`, for errors.
+- Text is always uppercase `hud`. Keep it short; a sentence belongs in body text.

package/guidelines/BudgetMeter.md

@@ -0,0 +1,11 @@
+# BudgetMeter
+
+How much of a budget is spent: a sunken `shell-recess` track (`shadow-press`) filled to the share spent, and a thin `ink` tick with a diamond head where today falls in the period.
+
+Provide `spent` and `budget` (minor units, BigInt), `label` (its accessible name, e.g. "Food budget") and optionally `elapsed` (0–1, the share of the period that has passed; omit it outside the period to hide the tick). `size` is `md` (12px track) or `sm` (8px, for history rows).
+
+- The fill is `signal` while within budget and turns `danger` once spending passes it; it stops at the end of the track.
+- Fill ahead of the tick means spending is ahead of the calendar.
+- It's a `meter` for assistive tech, valued in percent spent.
+- Always pair it with the figures in text ("12.34 USD of 100.00 USD spent", "Over by 2.34 USD"); color is never the only cue.
+- Put the period's dates under it, and a "◆ Today" caption under the tick.

package/guidelines/Button.md

@@ -0,0 +1,16 @@
+# Button
+
+Stadium-shaped molded button: signal orange for the main action, white shell for the second, and quieter variants for everything else.
+
+Provide `children` (label, sentence case, 1–3 words) and `onClick`. For a link, pass `asChild` and put an `<a>` (or your router link) inside. Optional `variant`, `size` and `arrow` (adds a mono →).
+
+- `default`: `signal` fill, `ink` label, `shadow-mold`. The main action of a block: "Start free trial", "Save changes". Never white text on signal.
+- `secondary`: `shell` fill with `shadow-mold`, for the second action, and the only button on a signal block.
+- `outline`: `shell` with a `seam` border, for form triggers and toolbar actions.
+- `ghost`: no fill until hover, for icon buttons and row actions.
+- `destructive`: `danger` fill with `shell` text. Only for the action that deletes.
+- `link`: `signal-ink` text with an underline on hover.
+- `bracket`: text wrapped in `signal-ink` mono brackets, `[ GitHub ]`. Inline links on cards and in the footer.
+- Pressed: moves down 1px and swaps to `shadow-press`. Focus: a `signal-ink` ring.
+- Height `control-height` (44px) by default, `radius-full`, `label` style. Sizes `xs`, `sm`, `lg` and the square `icon` sizes are for dense toolbars.
+- Icons are Lucide at `strokeWidth={1.25}`, before the label.

package/guidelines/Calendar.md

@@ -0,0 +1,8 @@
+# Calendar
+
+The month grid on its own, on react-day-picker. DatePicker wraps it in a field.
+
+Takes react-day-picker props: `mode` (`single`, `multiple`, `range`), `selected`, `onSelect`, `month`, `onMonthChange`, `disabled`. Weeks start on Monday and outside days show by default.
+
+- The caption is `hud` ("OCTOBER 2026"), weekdays are `hud-sm` in `ink-soft`.
+- Days are 36px stadiums in tabular mono. Selected: `signal` fill with `ink` text. Today: a `signal-ink` ring.

package/guidelines/CategoryIcon.md

@@ -0,0 +1,10 @@
+# CategoryIcon
+
+A category's Lucide glyph in `ink` on a disc of its palette color: the marker beside every transaction, budget and category row.
+
+Provide `icon` (a Lucide name from the curated set, e.g. `shopping-cart`) and `color` (a `cat-*` palette token). Optional `size` (`sm` 28px, `md` 36px default, `lg` 48px) and `label` (accessible name; omit when the category name sits next to it). `ColorDot` is the 10px dot used for labels.
+
+- Glyphs are 1.25px Lucide strokes in `ink`; every `cat-*` color keeps ink at 5.8:1 or better.
+- The disc is molded: a soft top highlight and bottom shade, no outline.
+- Transfers use `arrow-left-right` on `cat-slate`.
+- Pair it with the category name; color alone never identifies a category.

package/guidelines/Charts.md

@@ -0,0 +1,12 @@
+# Charts
+
+Recharts wrapped in Module/01 marks: thin lines, 4px rounded bar ends, a dashed `seam` grid, mono axis ticks in `ink-soft`, and a `hud-mark` baseline. Every chart has a hover tooltip: a `shell` card with a `hud-sm` title and tabular values in `ink`.
+
+- `BalanceChart` — one series over time: a 2px `chart-line` stroke over a `signal-tint` area, with a crosshair. A single series has no legend; the panel title names it.
+- `FlowChart` — income above the baseline in `chart-income`, expenses below it in `chart-expense`. Direction is a second cue besides color, and a legend sits under the plot. Pass `only` for a single series (no legend).
+- `DonutChart` — shares by category color, clockwise from 12 o'clock. The top 7 categories plus "Other" (`cat-slate`, `ellipsis` icon), 2px `shell` gaps between slices, and the total in the center (it shrinks to fit the hole). Every slice of 2% or more gets a callout outside the ring: a 1.5px leader in the slice color, the category's `CategoryIcon` (pass `icon` on each slice; without icons the marker is a color dot), and the share in `hud-sm` `ink` past it. Callouts are pushed apart around the ring so they never overlap, and the leader leaves from inside its own slice. On a narrow panel the shares drop out before the ring gets too small. Labels never sit on slices; still put the ranked list next to it, since it names every slice.
+
+Each takes `money` (`currency`, `minorUnits`) and amounts as BigInt minor units; tooltips format them with the sign and currency.
+
+- Axis ticks use compact numbers (`11.52K`) with enough digits that neighbours never read the same.
+- Never use two y-axes. Text never takes a series color.

package/guidelines/Checkbox.md

@@ -0,0 +1,8 @@
+# Checkbox
+
+A small sunken square that fills `signal` when checked.
+
+Takes Radix Checkbox props: `checked`, `defaultChecked`, `onCheckedChange`, `disabled`. Pair it with a Label through `id` and `htmlFor`.
+
+- Unchecked it's a `shadow-press` well; checked it carries an `ink` check on `signal`.
+- Use it for options that apply on submit. A setting that applies at once is a Toggle.

package/guidelines/Combobox.md

@@ -0,0 +1,18 @@
+# Combobox
+
+A searchable single-choice picker: a molded `shell` stadium trigger opening a `shell` popover with a search well and a list. Use it for categories, currencies and any list too long for a Select.
+
+Provide `value` and `onChange` (option keys), `options` (or `groups` with headings), `getKey`, and `renderOption`. Optional `getSearchText`, `renderValue`, `placeholder`, `searchPlaceholder`, `emptyText`, `footer` (e.g. "Edit categories →" in `hud-sm` `signal-ink`), `id`, `invalid`.
+
+- The trigger shows the selected option (glyph + name) or the placeholder in `ink-soft`, with a `chevrons-up-down` glyph at 1.25px.
+- Options are rows with the option's own glyph; the selected one carries a check at the end.
+
+## Form flow
+
+Forms built from kit controls move focus the way people fill them in, with no per-form wiring:
+
+- `Dialog` and `Sheet` open with focus on their first field (not the close button or tabs). If that field is an empty Combobox, its list opens too, once the entrance animation has finished.
+- **Type to search**: a letter on the focused trigger opens the list with that letter as the search.
+- **Pick to advance**: choosing an option (click or Enter) closes the list and focuses the next field. `Select` and `DatePicker` do the same. Escape returns to the trigger.
+- Tab follows layout order, so lay fields out in the order they are filled.
+- Rejected fields use the fault feedback (see Field).

package/guidelines/Command.md

@@ -0,0 +1,8 @@
+# Command
+
+A searchable list on cmdk: the engine inside Combobox, and a command palette on its own.
+
+Compose `Command` with `CommandInput`, `CommandList`, `CommandEmpty`, `CommandGroup` and `CommandItem`. `CommandDialog` puts it in a Dialog.
+
+- Reach for Combobox or MultiCombobox for form fields. Use Command directly for a palette or a custom picker.
+- Group headings are `hud-sm`; the empty state is one plain sentence.

package/guidelines/Crosshair.md

@@ -0,0 +1,7 @@
+# Crosshair
+
+12px plus-mark used as a registration mark on corners and image frames.
+
+Optional `tone` (`signal` uses `signal-ink`), `className`, `style` for positioning.
+
+- Default color `hud-mark`. Put one in a corner of panels and two on opposite corners of media frames; never more than two per part.

package/guidelines/CtaBanner.md

@@ -0,0 +1,8 @@
+# CtaBanner
+
+The big signal orange call to action at the foot of the page: a headline, a line of text, a grill and one shell button.
+
+Provide `title` and `action` (a `secondary` Button), optional `text` and `code` (microprint).
+
+- `signal` fill, `ink` text, `radius-xl` with a `notch-lg` cut, grill slots in `signal-shade`.
+- Once per page, before the footer. It's the largest orange surface; let it be.

package/guidelines/DatePicker.md

@@ -0,0 +1,11 @@
+# DatePicker
+
+A calendar date in a sunken well that opens a Module/01 month calendar, with Today and Yesterday shortcuts. `Calendar` is the month grid on its own.
+
+Provide `value` and `onChange` as `"YYYY-MM-DD"` strings (calendar dates have no time zone), plus `id` for its Field. Optional `placeholder` and `disabled`. `Calendar` takes react-day-picker props (`mode="single"`, `selected`, `onSelect`, `month`, `onMonthChange`).
+
+- The field matches TextInput: `shell-recess` well, `shadow-press`, `radius-md`, `control-height`, a 1.25px `calendar-days` glyph in `ink-soft`. Open, it takes a `signal-ink` border.
+- The label stays short: "Today, Oct 29", "Yesterday, Oct 28", "Tue, Oct 20"; the year appears only outside the current year.
+- The calendar sits in a `shell` popover with `shadow-float` and `radius-lg`. The caption is `hud` ("OCTOBER 2026"), weekdays are `hud-sm` in `ink-soft`, and weeks start on Monday.
+- Days are 36px stadiums in tabular mono. Selected: `signal` fill with `ink` text and `shadow-mold`. Today: a `signal-ink` ring. Other months' days: `hud-mark`.
+- Month arrows are small molded `shell` stadiums at the caption's right.

package/guidelines/Dialog.md

@@ -0,0 +1,9 @@
+# Dialog
+
+A centered modal part over an `overlay` scrim, on Radix Dialog.
+
+Compose `Dialog`, `DialogTrigger` and `DialogContent` with a `DialogHeader` (`DialogTitle`, `DialogDescription`) and a `DialogFooter`. `showCloseButton={false}` on the content drops the corner close button.
+
+- For short, focused tasks: a confirmation with a field or two. Longer editors open in a Sheet.
+- It opens with focus on its first field, not the close button. Don't add `autoFocus` inside.
+- The title names the task in plain words; the main action sits last in the footer.

package/guidelines/DropdownMenu.md

@@ -0,0 +1,9 @@
+# DropdownMenu
+
+A menu of actions that opens from a button, on Radix DropdownMenu.
+
+Compose `DropdownMenu`, `DropdownMenuTrigger` and `DropdownMenuContent` with `DropdownMenuItem`s. Labels, separators, groups, checkbox and radio items and submenus are available. `variant="destructive"` marks the deleting action.
+
+- Items are verbs in sentence case ("Rename", "Move to…"), with an optional Lucide glyph before the label.
+- Put the destructive item last, after a separator.
+- For actions. Choosing a value is a Select.

package/guidelines/Field.md

@@ -0,0 +1,22 @@
+# Field
+
+A form row: label, one control, then an error or help line. `TextInput` is the plain text well that goes in it; `FieldLabel` is the label on its own (FxConverter uses it).
+
+Provide `label` and `children` (the control), and `htmlFor` with the control's `id`. Optional `error` (turns the label `danger` with a fault LED; the message is announced to screen readers, not shown) or `help` (in `ink-soft`).
+
+- Labels use `body-sm` in `ink-soft`, sentence case, above the control with a 6px gap.
+- `TextInput` matches MoneyInput: `shell-recess` well, `shadow-press`, `radius-md`, `control-height`, `body-md` text.
+- Put "(optional)" in the label of optional fields instead of marking required ones.
+- Forms open in a side sheet on desktop and a bottom sheet on phones.
+
+## Fault feedback
+
+When a submit is rejected, the offending control reacts like a part refusing input. Call `fault(idOrElement)`, then set the Field's `error`.
+
+- **Servo jitter**: 320ms, ±3px horizontally, stepped (it jumps between positions, no easing), so it reads mechanical rather than wobbly.
+- **Ping**: one 2px `danger` ring leaves the part's outline and fades over 700ms, like a radar ping. No blur, no glow.
+- **Fault label**: the label turns `danger` and gains a 6px `danger` LED with a `danger-tint` halo that blinks three times and stays lit. No line under the control; the toast carries the message and screen readers hear it.
+- Focus moves to the control. A MoneyInput faults as one part; an FxConverter faults all three wells.
+- Editing the control clears its error. The toast still reports the problem too.
+- Reduced motion: no jitter or ping, just a short static `danger` outline.
+- Server rejections that name a field (`rate: amounts don't match…`) fault that field the same way.

package/guidelines/Footer.md

@@ -0,0 +1,7 @@
+# Footer
+
+Page foot: a tick ruler, microprint on either side and bracketed links in the middle.
+
+Provide `links` (`[{label, href}]`), and optional `left` and `right` microprint (build stamp, copyright) and `rulerLabels`.
+
+- Sits on `canvas`, no fill change. Microprint here is readable, so it uses `ink-soft`.

package/guidelines/FxConverter.md

@@ -0,0 +1,12 @@
+# FxConverter
+
+Three linked inputs for a cross-currency transfer: amount sent, amount received and the rate. Editing one recomputes the least recently edited of the other two.
+
+Provide `from` and `to` (`{code, minorUnits}`), a controlled `value` (start from `fx.initialFxState()`) and `onChange`. Read the result with `fx.fxResult(value, {fromMinorUnits, toMinorUnits})`: integer minor units for both sides plus the rate at 10 decimals, or null while incomplete.
+
+- The rule: `to = from × rate`, `from = to ÷ rate`, `rate = to ÷ from`. The field touched longest ago is overwritten by the other two. Before anything is touched, typing both amounts derives the rate, the usual case when copying a bank statement.
+- The field that will be recomputed next shows a small `auto` mark in `hud-mark`.
+- Rate means target units per one source unit, labelled "Rate (UYU per USD)". Computed rates show 6 decimals and keep 10 for storage.
+- Amounts round half-even to each currency's decimals.
+- Same-currency transfers show one MoneyInput instead.
+- Three columns from 32rem of its own width (a container query), stacked below that, so it fits sheets and cards at any viewport.

package/guidelines/GlassPanel.md

@@ -0,0 +1,8 @@
+# GlassPanel
+
+Frosted clear-plastic panel, like the UFO dome or a clear case, that lets what is behind it show through.
+
+Provide `children`. Use over something with color or texture (a studio image, the signal block, a grill); on plain canvas it disappears.
+
+- `glass` fill, 16px backdrop blur, `shadow-glass` edge highlight, `radius-lg`.
+- At most one or two per page beyond the nav bar. Text on it stays `ink`.

package/guidelines/Grill.md

@@ -0,0 +1,7 @@
+# Grill
+
+A row of stadium slots like a pegboard or speaker grill.
+
+Optional `count` (default 6), `slotWidth`, `gap`, `tone` (`recess` default, `signal` for orange slots on shell, `on-signal` for slots cut into a signal surface).
+
+- Slots are `radius-full`, sunken with `shadow-press`. Use as a texture on the hero side, the call-to-action block and card corners, a few slots at a time.

package/guidelines/Hero.md

@@ -0,0 +1,9 @@
+# Hero
+
+The opening shell: the page title or product name in Michroma, a subtitle and intro, actions, a spec row, and a studio image frame with grill and coordinates.
+
+Provide `title`. Optional `subtitle` (mono, `signal-ink`), `lead` (one or two sentences), `actions` (Buttons), `specs` (SpecReadout items), `image` (an `<img>`: a product shot, a screenshot, a portrait), `imageLabel`, `serial`, `coords` (microprint), or `media` to replace the image frame with your own.
+
+- `shell` part with `radius-xl` and a `notch-lg` cut, a `signal` hinge tab on its top edge, a signal crosshair bottom-right.
+- Title in `display-xl` (`display-lg` on phones); lead in `body-lg` `ink-soft`. The image sits on a `studio` backdrop; no image shows a crosshair placeholder.
+- One per page. It renders the page `h1`.

package/guidelines/HudLabel.md

@@ -0,0 +1,8 @@
+# HudLabel
+
+Mono overline with a signal code chip, a label and a seam rule that runs to an end marker.
+
+Provide `children` (label) and optional `code` (e.g. `S-02`), `end` (right-side microprint like `02/04`), `rule={false}` to drop the line.
+
+- The code chip is `signal` with `ink` text, `radius-xs`. Labels in `ink-soft`.
+- Sits `space-3` above every section heading and at the top of large panels.

package/guidelines/Input.md

@@ -0,0 +1,9 @@
+# Input
+
+The plain text well: `shell-recess` fill, `shadow-press`, `radius-md`, `control-height`.
+
+Takes every native `<input>` prop. Wrap it in a Field and pass the same `id` as the Field's `htmlFor`.
+
+- Text is `body-md` (16px), so phones don't zoom in on focus.
+- Focus adds a `signal-ink` ring. `aria-invalid` tints the well `danger-tint`.
+- Placeholders are examples ("Write a note"), in `ink-soft`. They never replace the label.

package/guidelines/Label.md

@@ -0,0 +1,7 @@
+# Label
+
+The accessible label for a control, on Radix Label.
+
+Provide `htmlFor` and `children`. Field renders one for you; use Label on its own beside a Checkbox or Toggle.
+
+- `body-sm`, sentence case. Clicking it focuses the control.

package/guidelines/MediaCard.md

@@ -0,0 +1,8 @@
+# MediaCard
+
+A card shot like a product: studio media frame with crosshairs and a code, kind and status, title, description, tags and bracket links, with an orange hinge tab. Use it for products, features, case studies, articles or projects.
+
+Provide `title`, and optional `code` (`C-01`), `image`, `imageAlt`, `kind` ("Product", "Case study"), `status` ("Live" gets a green LED; others a tint tag), `description` (1–2 sentences), `tags`, `links` (`[{label, href}]`), `hingeLeft`.
+
+- A Panel at `notch-md` with 14px inset; media on `studio` at `radius-md`.
+- Lay out two or three across with `space-8` gaps; vary `hingeLeft` so tabs don't line up.

package/guidelines/MoneyInput.md

@@ -0,0 +1,10 @@
+# MoneyInput
+
+A sunken decimal well for amounts, right-aligned in tabular mono, with the currency code as a suffix.
+
+Provide `currency` and the usual input props (`value`, `onChange`, `id`). The value is the raw string the person typed; parse it with `money.parseAmount(value, minorUnits)`, which returns integer minor units or null.
+
+- `shell-recess` fill with `shadow-press`, `radius-md`, `control-height`. Focus draws a `signal-ink` border and a soft ring.
+- Opens the decimal keypad on phones (`inputMode="decimal"`). On phones the figure grows to `amount-lg`: inputs under 16px make mobile browsers zoom in on focus. Search fields in pickers use `body-md` on phones for the same reason.
+- Invalid (`aria-invalid`): `danger` border on a `danger-tint` well; put the reason under it in a Field.
+- Amounts are entered positive; the transaction kind gives the direction.

package/guidelines/MultiCombobox.md

@@ -0,0 +1,11 @@
+# MultiCombobox
+
+A searchable multi-choice picker for "which ones count" fields, like a report's teams and tags. Selecting nothing means all, and the trigger then reads `allLabel` ("All teams").
+
+Takes the same option props as Combobox (`options` or `groups`, `getKey`, `getSearchText`, `renderOption`), plus `value` (selected keys), `allLabel` and `noun` (plural, for "3 teams").
+
+- The list stays open while you toggle options, with a check on each selected one. Escape or a click outside closes it back onto the trigger, and Tab moves on to the next field.
+- Typing on the focused trigger opens it with that text as the search, like Combobox.
+- With one option selected, the trigger shows it; with more, a count.
+- "Use all …" under the list clears the selection.
+- Use it in forms; for report filters in a toolbar, a smaller secondary button works the same way.

package/guidelines/NavBar.md

@@ -0,0 +1,10 @@
+# NavBar
+
+Floating frosted stadium bar: brand on the left, numbered links, and an end slot.
+
+Provide `brand` and `links` (`[{label, href, active}]`, 3–5). Optional `serial` (microprint under the brand), `end` (a StatusLed, a Button or a user menu) and `renderLink` to render links with your router.
+
+- `glass` with blur and `shadow-glass`, `radius-full`, `nav-height` (64px). Float it `space-4` from the top, sticky.
+- Links get mono numbers `01` `02`… on wide screens; the active one turns `signal-ink`.
+- Mark a link `desktopOnly` when the end slot offers it on phones.
+- It needs color or content scrolling behind it to read as glass.

package/guidelines/Panel.md

@@ -0,0 +1,10 @@
+# Panel
+
+The molded white part: a rounded shell with one hard notched corner, a serial in microprint and a corner crosshair.
+
+Provide `children`. Optional `serial` (microprint top-left, e.g. `W-01 · USD`), `notch` (`md` default, `sm`, `lg`, or `false`), `recess` (sunken `shell-recess` fill), `cross` (corner crosshair), `hinge` (left offset of a signal hinge tab) and `bodyClassName` (padding and layout of the inner part).
+
+- `shell` fill, `radius-lg`, padding `space-8`, lifted by `shadow-float` (as a drop-shadow so the notch keeps it). The notch sits top-right.
+- One notch per part, one hinge per part. Vary the hinge position from card to card.
+- Lists live in one Panel with `bodyClassName="p-0"`; summary tiles are small Panels with `notch="sm"`.
+- `HingeTab` is the tab on its own, for custom parts.

package/guidelines/Popover.md

@@ -0,0 +1,8 @@
+# Popover
+
+A floating `shell` part anchored to a trigger, on Radix Popover.
+
+Compose `Popover`, `PopoverTrigger` and `PopoverContent` (`align`, `side`, `sideOffset`). `PopoverHeader`, `PopoverTitle` and `PopoverDescription` give it a heading.
+
+- `shell` fill, `radius-lg`, `shadow-float`.
+- For pickers and small forms. Use the kit's pickers (Combobox, DatePicker) before building one by hand.