@franco_roura/module-01 0.0.0-stage → 1.0.0

package/guidelines/README.md

@@ -0,0 +1,100 @@
+A gadget you'd want on your desk: glossy white plastic parts, signal orange hardware, soft corners with one hard notch, and full HUD markings, like model codes, tick rulers, crosshairs and grill slots. Retro space-age product design meets an engineer's spec sheet. Module/01 is a kit for any app or website: landing pages, product and docs sites, dashboards, tools and data-dense apps. The rules below hold everywhere; Site surfaces and App surfaces add the patterns for each kind of screen.
+
+## Content fundamentals
+
+- Headings are plain words that name the thing: "Overview", "Pricing", "Reports", "Settings". Don't write them in character ("Mission log", "Operator profile").
+- The sci-fi lives in the labels around the copy: section codes (`S-02`), entry codes (`P-01`, `W-03`), serials (`UNIT-01 · REV.2026`), coordinates, build stamps. Keep codes short and consistent: letter, dash, two digits. Each product picks its own letters and uses them the same way on every screen.
+- Codes are decoration. Never make a code the only label for something; the plain heading or name always sits next to it.
+- Short and concrete. Speak to the reader in second person with plain verbs ("Start free trial", "Add member", "No results in this period"). Use first person only on a site about one person. Bullets start with a verb and carry one point.
+- Sentence case for headings and buttons; UPPERCASE only in the mono HUD styles. No emoji.
+
+## Color
+
+- The page is `canvas` (glossy white with a cool cast). Parts are `shell`, sunken areas `shell-recess`, joints `seam`.
+- `signal` is generous, like the trim on a product: primary buttons, hinge tabs on cards, HUD code chips, meter fills, grill accents, timeline nodes and feature blocks. Text on `signal` is always `ink`, never white.
+- Orange as text uses `signal-ink` (links, active nav, focus ring, emphasized lines); `signal` itself is too light for text on white.
+- `studio` (lavender-grey) is the backdrop behind every image, screenshot and portrait, as in a product shoot.
+- `visor` is black glass for terminal snippets and dark inset screens, with `shell` text and `visor-mark` microprint.
+- `glass` is frosted clear plastic: the nav bar, sticky bars and one or two `GlassPanel`s placed over color.
+- `led-on` green marks "available" and "live", always next to a word.
+- `hud-mark` is for decorative markings. Microprint that people need to read uses `ink-soft`.
+- `danger` fills destructive buttons (with `shell` text) and colors error text; `danger-tint` is the invalid input well.
+- `overlay` is the scrim behind dialogs and sheets.
+- Domain tokens are shared but only used where they apply: `income-ink`/`expense-ink` for signed money, `cat-red` … `cat-slate` (16 colors) for categories and labels, `chart-*` for chart series. See App surfaces.
+
+## Typography
+
+- Michroma (`--font-display`) for display only: the one hero title on a page, like a name or product name (`display-xl`), section and page headings (`display-lg`), feature block headlines (`display-md`), card and entry titles and the nav mark (`display-sm`). It's wide; keep headings short.
+- Manrope (`--font-sans`) for all reading: `body-lg` intros, `body-md` paragraphs and bullets, `body-sm` descriptions and captions, `label` (700) on buttons and nav.
+- Space Mono (`--font-mono`) for the HUD: `hud` labels and tags (uppercase, 0.12em), `hud-sm` microprint (uppercase, 0.16em), `hud-num` dates and small figures, `code` on visor.
+- Space Mono also sets numbers that matter: `amount-xl` headline figures, `amount-lg` tile and card figures, `amount-md` (700) row figures. Use tabular figures.
+- All three load from Google Fonts.
+
+## Shape
+
+- Soft parts with hard notches. Panels and cards are `radius-lg`; hero and feature blocks are `radius-xl`; media frames and inputs are `radius-md`. Each takes one chamfered corner, top-right: `notch-md` on panels and cards, `notch-lg` on hero and feature blocks, `notch-sm` on chips and small tiles.
+- Everything you press is a stadium (`radius-full`): buttons, tags, nav bar, grill slots, hinge tabs.
+- Hinge tabs are small `signal` stadiums sitting on a card's top edge, like the cube's hinges. Use one per card, and vary the position.
+
+## Depth and material
+
+- Parts float on `shadow-float` (applied as a drop-shadow so the notch keeps it). Buttons are molded with `shadow-mold`; pressed or sunken things use `shadow-press`.
+- Glass uses `shadow-glass` plus a 16px backdrop blur. It needs color behind it to read.
+
+## HUD markings
+
+- Every marking must sit on a structure: a code chip on each section label, a tick ruler under each section heading and above the footer, a serial in each panel's top-left corner, a crosshair in its bottom-right corner, two crosshairs on each media frame, and grill slots on hero and feature blocks.
+- One crosshair per panel corner pair, never a scatter. Rulers never run through text.
+- Sites go loud with markings. Apps keep the same structures but stay calmer where data is dense: lists and forms carry no decoration inside them, only on the panel around them.
+- Number in a stable order: sections `S-01`…, entries by a letter for their kind (`F-01` features, `R-01` records), nav links `01`…
+
+## Layout
+
+- Content max `content-max` (1120px), side padding `space-12` (`space-6` on mobile). Sections are `space-24` apart; a section header sits `space-12` above its content.
+- The glass NavBar floats over `canvas` and stays sticky. Grids of cards run 2–3 across with `space-8` gaps.
+
+## Imagery and iconography
+
+- Photos and renders go on a `studio` backdrop inside a `radius-md` frame. Use object shots and screenshots as product photos.
+- Markings are built from type and simple geometry: plus marks, brackets, ticks, slots, the → arrow in mono.
+- Interface icons come from Lucide at a 1.25px stroke, in `ink` or `signal-ink`.
+- Products have no logo by default. Set the product's name in Michroma wherever a mark would go, with a short form for tight spaces (`M/01`).
+
+## Site surfaces
+
+Sites (a landing page, a product or docs site, a portfolio) are editorial: few pages, big type, loud markings.
+
+- Page order: NavBar → Hero → Features (Panels) → Timeline (TimelineEntry stack) → Cards (MediaCard grid) → CtaBanner → Footer. Leave out what the page doesn't need.
+- The hero title is the page or product name in `display-xl`, with one image on `studio`.
+- `signal` carries the timeline nodes and the whole call-to-action block; `signal-ink` sets the hero subtitle.
+- Numbering: timeline `R-01`… (oldest first), cards `C-01`….
+
+## App surfaces
+
+Apps use the same parts for data-dense screens. Pages are a SectionHeader, then Panels.
+
+- Lists live in one Panel with no padding: a mono group header (a day, say) with its total, then rows. Rows hover to `shell-recess`.
+- Summary tiles are small Panels (`notch-sm`) with a `hud-sm` label over an `amount-lg` figure.
+- Inputs are sunken wells: `shell-recess`, `shadow-press`, `radius-md`, `control-height`. Wrap each in a Field. Dates use DatePicker; choices use Select, Combobox or MultiCombobox.
+- Forms flow on their own: dialogs and sheets open on the first field, Select, Combobox and DatePicker move focus to the next field after a pick, and typing on a combobox opens its search (see Combobox). MultiCombobox stays open while toggling and leaves with Tab.
+- A rejected input faults like a refusing part: a short stepped servo jitter, one thin `danger` ping leaving its outline, and its label turns `danger` with a blinking fault LED. Never a glow, never longer than a second (see Field).
+- Editors open in a sheet: from the right on desktop, from the bottom on phones. A signal stadium FAB opens quick-add on phones.
+- Bulk actions sit in a sticky glass stadium bar.
+- Serials label panels with the entity's code and one key fact (`R-01 · EU-WEST`).
+
+### Money and categories
+
+For products that handle money or categorized records.
+
+- Money as text: `income-ink` for positive amounts and balances, `expense-ink` for negative ones. Both always come with their sign. Every amount is integer minor units under the hood and shows its sign and currency (see Amount). Amounts are entered with MoneyInput; cross-currency transfers use FxConverter.
+- `cat-red` … `cat-slate` are the category and label palette: the disc behind a category glyph and the dot beside a label. Decorative fills; glyphs on them are `ink`. Category glyphs are Lucide icons on a palette disc (CategoryIcon).
+- Reports: a row of summary tiles, then chart Panels (balance, cash flow, category donuts with ranked lists). Series colors come from `chart-line`, `chart-income`, `chart-expense` and the category palette (see Charts).
+- Budgets: a grid of budget Panels (name, spent of budgeted, BudgetMeter, "left" or "over by", per-day allowance, period). The detail adds the meter with a today caption, category and account donuts, a history of periods with small meters, and the period's expenses.
+
+## Don'ts
+
+- Don't put white text on `signal`, and don't use `signal` as small text on white.
+- Don't show an amount without its sign, and don't rely on `income-ink`/`expense-ink` alone.
+- Don't put more than one notch on a part, and don't notch a stadium.
+- Don't use gradients, neon glows or dark mode. This system is lit like a white studio.
+- Don't write headings in character, and don't let a HUD code stand in for a heading. Keep the copy plain.

package/guidelines/SectionHeader.md

@@ -0,0 +1,9 @@
+# SectionHeader
+
+Section opener: HUD label with code, a plain display heading, and an optional tick ruler.
+
+Provide `title` (plain words: "Overview", "Settings"). Optional `code` (`S-02`), `label` (overline text), `aside` (a button or link at the right), `ruler`, and `as` (`h1` default, `h2`, `h3`).
+
+- Heading in `display-lg` (Michroma), `ink`; `display-md` on phones. Copy stays plain; the codes and ticks carry the sci-fi.
+- Leave `space-12` between the header and the content of the section.
+- One `h1` per page; use `as` for the sections under it.

package/guidelines/Select.md

@@ -0,0 +1,9 @@
+# Select
+
+A single choice from a short list, on Radix Select.
+
+Compose `Select`, `SelectTrigger` with a `SelectValue`, and `SelectContent` with `SelectItem`s. `SelectGroup`, `SelectLabel` and `SelectSeparator` structure longer lists.
+
+- For up to about eight options. A longer or searchable list is a Combobox.
+- The trigger is a sunken well like Input; the list is a `shell` popover with `shadow-float`.
+- Picking an option moves focus to the next field (see Combobox, Form flow).

package/guidelines/Separator.md

@@ -0,0 +1,8 @@
+# Separator
+
+A one-pixel `seam` line between groups, on Radix Separator.
+
+Optional `orientation` (`horizontal` default, `vertical`) and `decorative`.
+
+- Seams divide molded parts; they're never text and never thicker than a pixel.
+- Prefer spacing first. Add a seam when two groups would otherwise read as one.

package/guidelines/Sheet.md

@@ -0,0 +1,9 @@
+# Sheet
+
+A panel that slides in from an edge, for editors and filters. Built on Radix Dialog.
+
+Compose `Sheet`, `SheetTrigger` and `SheetContent` (`side`: `right` default, `left`, `top`, `bottom`) with a `SheetHeader`, your form, and a `SheetFooter`.
+
+- From the right on desktop at `sheet-max` (560px) wide; from the bottom on phones.
+- Like Dialog, it opens on its first field and keeps focus inside.
+- The footer holds the main action; keep it visible while the body scrolls.

package/guidelines/Skeleton.md

@@ -0,0 +1,8 @@
+# Skeleton
+
+A pulsing `shell-recess` block that holds the place of loading content.
+
+Size it with classes (`h-6 w-40`) to match what it replaces.
+
+- Mirror the shape of the real content: a line for text, a disc for a CategoryIcon, a block for a chart.
+- Show it only when loading takes long enough to notice.

package/guidelines/SpecReadout.md

@@ -0,0 +1,7 @@
+# SpecReadout
+
+A row of label/value pairs separated by seams, like a spec sheet.
+
+Provide `items`: `[{label, value}]` (3–5 items: location, focus, years, languages).
+
+- Labels in `hud` / `ink-soft`, values in `label` weight / `ink`. Seams in `seam`.

package/guidelines/SplitFlap.md

@@ -0,0 +1,9 @@
+# SplitFlap
+
+Text whose characters flip through random glyphs before landing, like a station departure board.
+
+Provide `text`. Optional `start` (hold the first flap until true, e.g. when scrolled into view).
+
+- Use it on HUD microprint: a status line, a clock, a code. Never on headings or body text.
+- It flaps again whenever `text` changes; unchanged characters stay still.
+- Screen readers get the final text only. Reduced motion skips the flipping.

package/guidelines/StatusLed.md

@@ -0,0 +1,8 @@
+# StatusLed
+
+A small LED dot with a mono label, for availability and live states.
+
+Provide `children` (the status in words: "Online", "Synced"). Optional `tone` (`on` default green `led-on`, `signal`, `off`).
+
+- Always a word next to the dot; color alone never carries the meaning.
+- One per area: the nav and the hero.

package/guidelines/Tabs.md

@@ -0,0 +1,9 @@
+# Tabs
+
+A row of stadium tabs that switch the view under them, on Radix Tabs.
+
+Compose `Tabs` (`value` or `defaultValue`) with a `TabsList` of `TabsTrigger`s and one `TabsContent` per tab. `TabsList` takes `variant` `default` or `line`.
+
+- The list is a sunken `shell-recess` track; the active tab is a raised `shell` stadium with `shadow-mold`.
+- Two to five tabs with one-word labels. More than that is a Select.
+- In a form, tabs that switch its kind ("Expense", "Income", "Transfer") sit above the first field.

package/guidelines/Tag.md

@@ -0,0 +1,9 @@
+# Tag
+
+Small stadium chip in mono uppercase for skills, stacks and status.
+
+Provide `children` (one or two words). Optional `tone` (`signal`, `tint`, `outline`; recessed by default), `led` (adds a green LED dot, for "Live"), and `interactive` with `pressed` and `onClick` to render a keycap button.
+
+- Default: `shell-recess` fill, like a slot molded into the part. `outline` on shell cards; `signal` for the one tag that matters most; `tint` for in-progress states.
+- Text is always uppercase `hud` at 12px.
+- In an app, use Badge; Tag adds the LED and the keycap for sites.

package/guidelines/Terminal.md

@@ -0,0 +1,7 @@
+# Terminal
+
+Black-glass visor screen for a few lines of code or commands.
+
+Provide `lines` (array of strings, shown after a `signal` `$` prompt) and optional `title` (microprint).
+
+- `visor` fill, `shell` text, `code` style, `radius-md`. Use for an install command or a fun one-liner; keep to 1–4 lines.

package/guidelines/Textarea.md

@@ -0,0 +1,8 @@
+# Textarea
+
+A multi-line well for notes and descriptions.
+
+Takes every native `<textarea>` prop. Wrap it in a Field.
+
+- It grows with its content from a 64px minimum.
+- Same focus ring and invalid treatment as Input.

package/guidelines/TickRuler.md

@@ -0,0 +1,8 @@
+# TickRuler
+
+Measurement-tape strip of minor and major ticks, with optional microprint numbers.
+
+Optional `labels` (array of short strings spread evenly under the ticks).
+
+- Major ticks every 40px in `hud-mark`, minor every 8px in `seam`.
+- Decorative: hidden from assistive tech. Use under section headings and above the footer, not inside paragraphs.

package/guidelines/TimelineEntry.md

@@ -0,0 +1,8 @@
+# TimelineEntry
+
+One entry on a timeline track: a job, a release, a milestone. Date range and code, title, subtitle, bullet points and tags.
+
+Provide `title`, `start`, and optional `subtitle` (a company, team or product), `end` (defaults to "Now"), `current` (orange node; past entries get a hollow node), `code` (`R-03`), `detail` (a place or a version), `points` (2–4 short bullets), `tags`.
+
+- Dates in `hud-num`; title in `display-sm`; subtitle in `body-sm` `ink-soft`; bullets in `body-md` with `signal-ink` markers.
+- Stack entries newest first; the track line runs between them in `seam`.

package/guidelines/Toaster.md

@@ -0,0 +1,9 @@
+# Toaster
+
+Toasts on sonner, in Module/01 colors.
+
+Mount `<Toaster />` once at the root, then call `toast()`, `toast.success()` or `toast.error()` from `sonner`.
+
+- A toast confirms what just happened ("Changes saved") or reports a problem. One short sentence, no period.
+- When a form field is rejected, fault the field as well (see Field); the toast carries the message.
+- Never put the only copy of important information in a toast: it leaves.

package/guidelines/Toggle.md

@@ -0,0 +1,9 @@
+# Toggle
+
+A button that stays pressed, on Radix Toggle. `ToggleGroup` holds a set of them.
+
+`Toggle` takes `pressed`, `onPressedChange`, `variant` (`default`, `outline`) and `size`. `ToggleGroup` takes `type` (`single` or `multiple`), `value`, `onValueChange`, and `ToggleGroupItem`s.
+
+- Pressed is a sunken state: `shell-recess` with `shadow-press`.
+- For view options that apply at once (a chart mode, bold). An option saved with a form is a Checkbox.
+- Give icon-only toggles an `aria-label`.

package/guidelines/Tooltip.md

@@ -0,0 +1,8 @@
+# Tooltip
+
+A short `ink` label that names a control on hover and focus, on Radix Tooltip.
+
+Wrap the app once in `TooltipProvider`, then compose `Tooltip`, `TooltipTrigger` and `TooltipContent`.
+
+- For icon buttons and truncated text. One short phrase, no punctuation.
+- Never put information there that people need to finish a task: touch screens have no hover.

package/package.json

@@ -1,6 +1,105 @@
 {
   "name": "@franco_roura/module-01",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Module/01: React components for a design system of glossy white parts, signal orange trim and HUD markings.",
+  "keywords": [
+    "components",
+    "design-system",
+    "module-01",
+    "radix-ui",
+    "react",
+    "tailwindcss"
+  ],
+  "homepage": "https://franco-roura.github.io/module-01/",
+  "bugs": "https://github.com/franco-roura/module-01/issues",
+  "license": "(MIT OR Apache-2.0)",
+  "author": "Franco Roura",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/franco-roura/module-01.git",
+    "directory": "packages/module-01"
+  },
+  "files": [
+    "dist",
+    "tokens",
+    "guidelines",
+    "LICENSE-MIT",
+    "LICENSE-APACHE"
+  ],
+  "type": "module",
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./finance": {
+      "types": "./dist/finance.d.ts",
+      "default": "./dist/finance.js"
+    },
+    "./charts": {
+      "types": "./dist/charts.d.ts",
+      "default": "./dist/charts.js"
+    },
+    "./site": {
+      "types": "./dist/site.d.ts",
+      "default": "./dist/site.js"
+    },
+    "./theme.css": "./dist/theme.css",
+    "./styles.css": "./dist/styles.css",
+    "./tokens.css": "./dist/tokens.css",
+    "./tokens.json": "./tokens/tokens.json",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "tokens": "node scripts/build-tokens.ts",
+    "build": "node scripts/build-tokens.ts && vp pack && node scripts/build-css.ts",
+    "test": "vp test run",
+    "typecheck": "tsc --noEmit",
+    "size": "size-limit",
+    "lint:package": "publint && attw --pack . --profile esm-only --exclude-entrypoints theme.css styles.css tokens.css"
+  },
+  "dependencies": {
+    "class-variance-authority": "0.7.1",
+    "clsx": "2.1.1",
+    "cmdk": "1.1.1",
+    "date-fns": "4.4.0",
+    "lucide-react": "1.65.0",
+    "radix-ui": "1.8.1",
+    "react-day-picker": "10.0.2",
+    "sonner": "2.0.8",
+    "tailwind-merge": "3.7.0",
+    "tw-animate-css": "1.4.0"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "0.18.5",
+    "@size-limit/preset-small-lib": "14.3.0",
+    "@tailwindcss/cli": "4.3.3",
+    "@testing-library/react": "16.3.3",
+    "@types/node": "26.6.6",
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
+    "happy-dom": "21.0.4",
+    "publint": "0.3.25",
+    "react": "19.3.1",
+    "react-dom": "19.3.1",
+    "recharts": "3.10.1",
+    "size-limit": "14.3.0",
+    "tailwindcss": "4.3.3"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "recharts": "^3.10.1"
+  },
+  "peerDependenciesMeta": {
+    "recharts": {
+      "optional": true
+    }
+  }
+}