{ "system": { "name": "Poesía", "package": "@rrios-forge/ui", "version": "0.16.1", "canon": "Material-first: vibrant glass is the system's material (ADR-027, J-01).", "build": { "commit": "9aa2fe8c", "branch": "main", "committedAt": "2026-10-21T10:08:16+02:00", "generatedAt": "2026-10-21T08:14:37.860Z", "gatesRanAt": "2026-10-21T08:14:37.855Z" }, "principles": [ { "id": "P01", "title": "Semantic First", "summary": "Every entity is named and organized by intent, not appearance." }, { "id": "P02", "title": "Accessible by Default", "summary": "Accessibility is an input condition, not a final audit." }, { "id": "P03", "title": "Technology Agnostic Core", "summary": "The Core is expressed as contracts and data, not as React/Tailwind/shadcn implementation." }, { "id": "P04", "title": "Theme-Native", "summary": "The system is designed for modes, brands and visual flavors without breaking semantics." }, { "id": "P05", "title": "Composable by Design", "summary": "Complex solutions should be composed from reusable pieces and rules." }, { "id": "P06", "title": "Constraint over Preference", "summary": "Decisions are justified by constraints, context and objectives, not subjective taste." }, { "id": "P07", "title": "Explicit Decision", "summary": "Every relevant change must have a traceable decision, validation and rationale." }, { "id": "P08", "title": "Progressive Complexity", "summary": "No layer, rule, token or pattern is added unless it solves a real need." }, { "id": "P09", "title": "Resilient Versioning", "summary": "The system must evolve without breaking consumers unless an explicit decision allows it." }, { "id": "P10", "title": "Calm Interface", "summary": "The interface does not compete with the content for attention; decoration comes last." }, { "id": "P11", "title": "Hierarchy by Restraint", "summary": "Hierarchy comes from few, consistent means — size, weight, position — not from more of everything." } ], "rules": [ { "id": "R01", "title": "Declared intent", "summary": "Every core entity must declare intent." }, { "id": "R02", "title": "No appearance-only naming", "summary": "No core entity may be named only by visual appearance." }, { "id": "R03", "title": "Agnostic core", "summary": "The Core must not contain code or syntax dependent on React, Tailwind, shadcn or any other implementation." }, { "id": "R04", "title": "Tokens for visual values", "summary": "Every visual value consumed by implementation must go through a token." }, { "id": "R05", "title": "WCAG AA contrast", "summary": "Every token-defined text/background pair must be able to validate minimum WCAG 2.1 AA contrast. AAA is recommended for high-contrast themes but not required as the global baseline." }, { "id": "R06", "title": "Themes override values, not semantics", "summary": "A theme/flavor may override values, but must not create new semantics." }, { "id": "R07", "title": "Rule contract", "summary": "Every rule must declare scope, severity, validation type and exception policy." }, { "id": "R08", "title": "Documented exceptions", "summary": "Every exception must declare reason, affected rule, scope and review date." }, { "id": "R09", "title": "Decisions cite contracts", "summary": "Every relevant decision must link to at least one principle or rule." }, { "id": "R10", "title": "Extend before creating", "summary": "A new entity must not be created if an existing one can be extended without breaking semantics." }, { "id": "R11", "title": "Pattern contract", "summary": "Every pattern must declare problem, context, intent, applied rules and limits." }, { "id": "R12", "title": "Token contract", "summary": "Every token must have category, purpose, lifecycle state and source." }, { "id": "R13", "title": "No circular references", "summary": "References between tokens, themes and semantic roles must not be circular." }, { "id": "R14", "title": "Aesthetics never override safety", "summary": "Aesthetic rules must never outrank semantic, accessibility or functional rules." }, { "id": "R15", "title": "Experimental entities are bounded", "summary": "Every experimental entity must declare usage limits and stabilization or removal criteria." } ], "axes": { "intent": { "meaning": "What an action does.", "values": [ "primary", "secondary", "neutral", "danger" ] }, "tone": { "meaning": "Which semantic colour family the element speaks in.", "values": [ "neutral", "muted", "inverse", "info", "success", "warning", "danger" ] }, "emphasis": { "meaning": "How strongly a control or chip asserts itself, quiet to loud.", "values": [ "ghost", "outline", "soft", "solid" ] }, "prominence": { "meaning": "How a surface stands among its siblings.", "values": [ "subtle", "default", "featured" ] }, "surface": { "meaning": "Which surface level a container paints.", "values": [ "default", "muted", "raised" ] }, "material": { "meaning": "The layer's material (ADR-022, ADR-027).", "values": [ "vibrant", "solid" ] }, "size": { "meaning": "Ergonomic scale, in three families (control, text, container).", "values": [ "xs", "sm", "md", "lg", "xl", "full", "prose", "fluid", "display" ] }, "kind": { "meaning": "What an avatar stands for — a person (round) or an entity such as a workspace or brand (rounded square) (ADR-039).", "values": [ "person", "entity" ] }, "shape": { "meaning": "Geometry, where geometry is the meaning.", "values": [ "circle", "rounded", "text", "rectangle" ] }, "presentation": { "meaning": "How the same thing is staged.", "values": "open" }, "lockup": { "meaning": "Which form of the brand mark.", "values": [ "full", "mark" ] }, "ground": { "meaning": "Which ground a brand mark sits on.", "values": [ "auto", "light", "dark" ] }, "palette": { "meaning": "Brand colour or monochrome for a brand mark.", "values": [ "brand", "mono" ] }, "form": { "meaning": "Which chart form encodes the data — chosen by the data's job, never by the look (ADR-036).", "values": [ "line", "area", "column" ] }, "orientation": { "meaning": "The direction the parts run: a row (horizontal) or a column (vertical); responsive stacks on phones and runs in a row from sm.", "values": [ "horizontal", "vertical", "responsive" ] }, "layout": { "meaning": "Arrangement of a composite.", "values": "open" }, "align": { "meaning": "Distribution along the main axis.", "values": [ "start", "center", "end", "between" ] }, "side": { "meaning": "Which side something belongs to.", "values": "open" }, "position": { "meaning": "Placement of a docked element.", "values": "open" }, "placement": { "meaning": "Where an attached element sits.", "values": "open" }, "gap": { "meaning": "Spacing between grid items.", "values": [ "none", "xs", "sm", "md", "lg", "xl" ] }, "rowGap": { "meaning": "Spacing between grid rows.", "values": [ "none", "xs", "sm", "md", "lg", "xl" ] }, "alignX": { "meaning": "Inline-axis alignment of grid items.", "values": [ "start", "center", "end", "stretch" ] }, "alignY": { "meaning": "Block-axis alignment of grid items.", "values": [ "start", "center", "end", "stretch", "baseline" ] }, "padding": { "meaning": "Inner spacing of a container.", "values": [ "none", "sm", "md", "lg" ] }, "inset": { "meaning": "Inner spacing of a sheet section.", "values": [ "sm", "md", "lg" ] }, "weight": { "meaning": "Type weight within the ramp.", "values": [ "regular", "medium", "semibold" ] }, "status": { "meaning": "Progress state of a step.", "values": "open" }, "type": { "meaning": "Which loading indicator.", "values": "open" }, "display": { "meaning": "What a selector shows.", "values": "open" }, "visibility": { "meaning": "When an affordance shows.", "values": "open" }, "motion": { "meaning": "Ambient motion of the atmosphere (ADR-023).", "values": [ "drift", "still" ] }, "energy": { "meaning": "Resting tempo of the atmosphere (ADR-023).", "values": [ "calm", "lively" ] }, "signal": { "meaning": "Ambient escalation (ADR-023).", "values": [ "none", "raised", "urgent" ] }, "frame": { "meaning": "PageShell editorial frame.", "values": "open" }, "scroll": { "meaning": "PageShell scroll owner.", "values": "open" }, "stage": { "meaning": "PageShell stage paint.", "values": "open" }, "sidebarMode": { "meaning": "How the app frame shows its navigation: rail, the default, is a column of icons whose rows preview their page; auto and panel show the labelled panel instead.", "values": "open" }, "mainPadding": { "meaning": "PageShell main padding.", "values": "open" }, "columns": { "meaning": "How many columns a grid layout takes from its widest breakpoint (ADR-039).", "values": "open" }, "disabled": { "meaning": "Not available: dimmed, skipped by the keyboard, ignores the pointer.", "values": "boolean" }, "invalid": { "meaning": "Fails validation: a danger edge, announced as invalid; pair it with an error message.", "values": "boolean" }, "selected": { "meaning": "Chosen in a set: the selected wash plus a non-colour cue (weight, check).", "values": "boolean" }, "active": { "meaning": "The current destination or item: marked as current to assistive tech.", "values": "boolean" }, "interactive": { "meaning": "Responds to the pointer: hover and press feedback, a pointer cursor.", "values": "boolean" }, "unread": { "meaning": "Not yet seen: a dot and stronger weight until opened.", "values": "boolean" }, "today": { "meaning": "Marks the current day in a calendar.", "values": "boolean" }, "dragging": { "meaning": "Something is being dragged over it: the drop target lights up.", "values": "boolean" }, "filled": { "meaning": "Holds a value: the label stays raised over the field.", "values": "boolean" }, "collapsed": { "meaning": "Folded to its compact form (an icon rail, a closed group).", "values": "boolean" }, "idle": { "meaning": "Waiting, with nothing to show yet.", "values": "boolean" }, "fill": { "meaning": "Card grows to its row's tallest sibling (ADR-012).", "values": "boolean" }, "bleed": { "meaning": "Sheet section runs edge to edge.", "values": "boolean" }, "centered": { "meaning": "Container centres itself.", "values": "boolean" }, "dense": { "meaning": "Grid packs items densely.", "values": "boolean" }, "lead": { "meaning": "AvatarGroup leading avatar emphasis.", "values": "boolean" }, "overlap": { "meaning": "ProfileHeader avatar overlaps the cover (ADR-039).", "values": "boolean" } }, "layers": [ { "name": "dark", "description": "Dark mode theme. Inverts neutrals and lifts brand/status colors to remain WCAG AA compliant on dark backgrounds.", "layer": "mode", "attributes": { "data-color-scheme": "dark" } }, { "name": "desktop-density", "description": "Opt-in density theme for desktop applications. Tightens spacing, switches the UI face to the platform system font and shortens the default transition, so that information-dense panels read at a glance. (A one-notch smaller type scale is planned with the typography roles; until then the type ramp is not themeable.) Overrides values only: every semantic name keeps its meaning, so a component authored against the base scale needs no change. Web surfaces are unaffected unless they set data-theme=\"desktop-density\" explicitly.", "layer": "density", "attributes": { "data-density": "desktop" } }, { "name": "full-transparency-dark", "description": "The default material at night, restated for a data-transparency=\"full\" subtree (J-44). Overrides values only.", "layer": "accessibility", "attributes": { "data-color-scheme": "dark", "data-transparency": "full" } }, { "name": "full-transparency", "description": "The default material restated (ADR-042 revision, J-44): a subtree marked data-transparency=\"full\" shows the glass and content materials as designed whatever the page's material layer says — for a specimen that compares materials side by side. The OS-level prefers-reduced-transparency still wins. Overrides values only.", "layer": "accessibility", "attributes": { "data-transparency": "full" } }, { "name": "high-contrast-dark", "description": "High contrast at night: applies where dark mode and high contrast meet (data-mode=\"dark\" with data-contrast=\"more\", or a dark page whose reader asked the OS for more contrast). Black surfaces, white text and boundaries, the action labels and the focus ring lifted to the 200 step, and the vibrant material collapsed to an opaque pane. Overrides values only.", "layer": "accessibility", "attributes": { "data-color-scheme": "dark", "data-contrast": "more" } }, { "name": "high-contrast", "description": "High-contrast accessibility theme. Lifts foreground/background pairs to AAA where it matters; minimal overrides for Phase 2.", "layer": "accessibility", "attributes": { "data-contrast": "more" } }, { "name": "less-transparency-dark", "description": "'Content' material at night (ADR-042): the glass layer takes the night content material. Overrides values only.", "layer": "accessibility", "attributes": { "data-color-scheme": "dark", "data-transparency": "less" } }, { "name": "less-transparency", "description": "The reader's material choice 'content' (ADR-042): the glass layer takes the thick content material — the sky diffused into colour, no sheen, rim or halo. Overrides values only.", "layer": "accessibility", "attributes": { "data-transparency": "less" } }, { "name": "light", "description": "Default light theme. Semantic tokens already encode the light palette, so this theme intentionally has no overrides — including the action LABEL split (action.*-quiet), whose light value lives in the reference layer as brand.*-quiet.", "layer": "base", "attributes": { "data-color-scheme": "light" } }, { "name": "reduced-motion", "description": "Accessibility theme that minimizes motion. Reduces transition durations near zero. Keeps easing semantics intact.", "layer": "accessibility", "attributes": { "data-motion": "reduce" } }, { "name": "reduced-transparency-dark", "description": "'Solid' material at night (ADR-042): panes opaque on the night raised surface. Overrides values only.", "layer": "accessibility", "attributes": { "data-color-scheme": "dark", "data-transparency": "reduce" } }, { "name": "reduced-transparency", "description": "The reader's material choice 'solid' (ADR-042), the same collapse prefers-reduced-transparency gives: every pane opaque on the raised surface, no blur, sheen or halo. Overrides values only.", "layer": "accessibility", "attributes": { "data-transparency": "reduce" } } ], "gates": [ { "check": "Types", "command": "bun run check-types", "inCi": "yes", "state": "not-run", "note": "Checked by the CI job packages, not by the Atlas." }, { "check": "Lint", "command": "bun run lint", "inCi": "yes", "state": "not-run", "note": "Checked by the CI job packages, not by the Atlas." }, { "check": "R02 / R04 / atoms-only", "command": "bash .claude/hooks/poesia-lint-forbidden.sh --tree", "inCi": "yes (`guards`)", "state": "pass", "note": "poesia-lint-forbidden: árbol limpio.", "durationMs": 16145 }, { "check": "Token tiers, references, cycles", "command": "bun run tokens:validate", "inCi": "yes", "state": "pass", "note": "@rrios-forge/design-system-tokens validate: tokens: validation passed (primitives=313, reference=203, semantic=191 leaves).", "durationMs": 54 }, { "check": "Contrast per theme", "command": "bun run tokens:contrast", "inCi": "yes", "state": "pass", "note": "@rrios-forge/design-system-tokens contrast: tokens contrast: 158 pair-checks pass WCAG AA across light, dark, high-contrast, high-contrast-dark.", "durationMs": 58 }, { "check": "Themes override existing semantics only", "command": "bun run themes:validate", "inCi": "yes", "state": "pass", "note": "@rrios-forge/design-system-themes validate: themes: validation passed.", "durationMs": 41 }, { "check": "Theme tests (density order, OS reduce-motion last)", "command": "bun --filter @rrios-forge/design-system-themes test", "inCi": "yes", "state": "pass", "note": "@rrios-forge/design-system-themes test: themes: check OK — 5 theme(s), 707 token paths", "durationMs": 57 }, { "check": "Generated output in sync", "command": "bun run ds:build && git diff --exit-code -- packages/design-system-tokens/generated packages/design-system-themes/generated", "inCi": "yes", "state": "not-run", "note": "Runs as part of the build that publishes this Atlas." }, { "check": "Inventory, story metadata, server boundary, ADR citations", "command": "cd tooling/storybook && bun run check:inventory && bun run check:story-meta && bun run check:server-boundary && bun run check:citations", "inCi": "yes", "state": "pass", "note": "check-citations: 374 citations in 46 ADRs match principles.yaml (P01–P11) and rules.yaml (15 rules).", "durationMs": 161 }, { "check": "Storybook builds", "command": "bun run storybook:build", "inCi": "yes", "state": "not-run", "note": "Runs as part of the build that publishes this Atlas." }, { "check": "Axis vocabulary, focus ring", "command": "cd tooling/storybook && bun run check:axes -- --strict && bun run check:focus-ring", "inCi": "yes", "state": "pass", "note": "check-focus-ring: 507 files in packages/ui/src; every focus ring comes from lib/focus-ring.ts.", "durationMs": 126 }, { "check": "Taste: generic-AI tells in source (`taste.yaml`, J-13)", "command": "cd tooling/storybook && bun run check:taste", "inCi": "reported, not blocking (C-30)", "state": "pass", "note": "check-taste: 80 finding(s) in 36 of 847 files, 7 of 11 lint tells (report mode, C-30).", "durationMs": 193 }, { "check": "Visual snapshots + axe + play tests", "command": "bun run storybook:test (needs Playwright's Chromium)", "inCi": "job `poesia-visual`, off until `POESIA_VISUAL=true`", "state": "off", "note": "Browser gates are off in CI until the runner has Playwright (POESIA_VISUAL)." }, { "check": "Glass gate", "command": "cd tooling/storybook && bun run test:glass (headed)", "inCi": "job `poesia-visual`, same switch", "state": "off", "note": "Browser gates are off in CI until the runner has Playwright (POESIA_VISUAL)." }, { "check": "Legibility, gutters", "command": "cd tooling/storybook && bun run check:legibility && bun run check:gutters (headed)", "inCi": "no — run locally", "state": "not-run", "note": "Headed browser check, run locally." } ], "decisions": [ { "id": "ADR-001", "title": "Token sources are JSON, not TypeScript", "status": "accepted", "date": "2026-04-25", "url": "https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-001-token-sources-are-json.md" }, { "id": "ADR-002", "title": "Component variants live in `variants.ts` and export their option metadata", "status": "accepted", "date": "2026-04-26", "url": "https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-002-component-variants-in-variants-ts.md" }, { "id": "ADR-003", "title": "Storybook editorial convention and pattern↔component bidirectionality", "status": "accepted", "date": "2026-04-27", "url": "https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-003-storybook-editorial-convention.md" }, { "id": "ADR-004", "title": "Migrate boolean configuration props to semantic axes", "status": "accepted", "date": "2026-04-27", "url": "https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-004-boolean-props-to-semantic-axes.md" }, { "id": "ADR-005", "title": "Visual operational rules: surfaces, interaction, motion", "status": "accepted", "date": "2026-04-27", "url": "https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-005-visual-operational-rules.md" }, { "id": "ADR-006", "title": "Geometry and typography signature", "status": "accepted", "date": "2026-04-27", "url": "https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-006-geometry-and-typography-signature.md" }, { "id": "ADR-007", "title": "Material highlight on raised surfaces", "status": "accepted", "date": "2026-04-27", "url": "https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-007-material-highlight-on-raised-surfaces.md" }, { "id": "ADR-008", "title": "Layout layer: refined `Grid` + new `Container`", "status": "accepted", "date": "2026-04-28", "url": "https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-008-layout-layer-grid-and-container.md" }, { "id": "ADR-009", "title": "Editorial Frame: PageShell v3 + new `TopBar` molecule", "status": "accepted · amended in part by ADR-011", "date": "2026-04-28", "url": "https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-009-editorial-frame-page-shell.md" }, { "id": "ADR-010", "title": "PageShell v4: bottom dock + mobile floating bubble", "status": "accepted · superseded in part by ADR-011 (navigation)", "date": "2026-04-28", "url": "https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-010-page-shell-bottom-dock.md" }, { "id": "ADR-011", "title": "PageShell v5: adaptive lateral sidebar + mobile nav bubble", "status": "accepted · amended by ADR-013 (mobile nav) and ADR-014 (rail at md)", "date": "2026-04-29", "url": "https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-011-pageshell-v5-mobile-nav-bubble.md" }, { "id": "ADR-012", "title": "Card.fill axis for symmetric growth in grids", "status": "accepted", "date": "2026-04-29", "url": "https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-012-card-fill-axis.md" }, { "id": "ADR-013", "title": "PageShell: mobile-nav polymorphism", "status": "accepted", "date": "2026-05-06", "url": "https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-013-pageshell-mobile-nav-polymorphism.md" }, { "id": "ADR-014", "title": "PageShell: Apple Mail / macOS Big Sur visual register", "status": "accepted · amended by ADR-022 §5", "date": "2026-05-06", "url": "https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-014-pageshell-apple-mail-register.md" }, { "id": "ADR-015", "title": "Drawer molecule on top of Radix Dialog", "status": "accepted", "date": "2026-05-08", "url": "https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-015-drawer-molecule.md" }, { "id": "ADR-016", "title": "NotificationCenter v2: Popover → Drawer + Provider/Hooks", "status": "accepted", "date": "2026-05-08", "url": "https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-016-notification-center-drawer-provider.md" }, { "id": "ADR-017", "title": "Actionable components adopt the `asChild` slot pattern for framework-aware routing", "status": "accepted", "date": "2026-05-08", "url": "https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-017-actionable-as-child-pattern.md" }, { "id": "ADR-018", "title": "Motion language as a Pattern Layer contract", "status": "accepted", "date": "2026-05-09", "url": "https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-018-motion-language-pattern.md" }, { "id": "ADR-019", "title": "Composer organism (message/post authoring surface)", "status": "accepted", "date": "2026-07-22", "url": "https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-019-composer-organism.md" }, { "id": "ADR-020", "title": "Feed `anchor=\"bottom\"` (conversation mode) instead of a ChatThread organism", "status": "accepted", "date": "2026-07-22", "url": "https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-020-feed-anchor-bottom.md" }, { "id": "ADR-021", "title": "ProfileHeader organism and the `cover` slot contract", "status": "accepted", "date": "2026-07-22", "url": "https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-021-profile-header-organism.md" }, { "id": "ADR-022", "title": "The material family: `solid` and `vibrant`", "status": "accepted · amended by ADR-027 (vibrant becomes the default)", "date": "2026-08-06", "url": "https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-022-material-family-vibrant.md" }, { "id": "ADR-023", "title": "Atmosphere grammar: colour, motion, and meaning", "status": "accepted · 2026-08-07", "date": null, "url": "https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-023-atmosphere-grammar.md" }, { "id": "ADR-024", "title": "`LocaleSelector` is a new molecule, not an extension of `Combobox`", "status": "accepted (renumbered 2026-08-08: born as a second ADR-008, colliding with the Layout Layer ADR; IDs must be unique)", "date": "2026-05-06", "url": "https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-024-locale-selector.md" }, { "id": "ADR-025", "title": "The sidebar is an island, not a wall (amended: two stagings)", "status": "accepted · amended 2026-08-08 (M-11: production audit added the `column` staging + absorbed RailTooltip / icon-cell)", "date": "2026-08-08", "url": "https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-025-sidebar-island.md" }, { "id": "ADR-026", "title": "Sunset functional palette + the stage field", "status": "accepted", "date": "2026-08-08", "url": "https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-026-sunset-functional-palette.md" }, { "id": "ADR-027", "title": "Vibrant is the system's material, not one of its members", "status": "accepted · amended by ADR-029 (reading sheets)", "date": "2026-08-08", "url": "https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-027-vibrant-is-the-system.md" }, { "id": "ADR-028", "title": "The label is not the fill", "status": "accepted", "date": "2026-08-09", "url": "https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-028-label-is-not-the-fill.md" }, { "id": "ADR-029", "title": "The page gutter belongs outside the frame", "status": "accepted", "date": "2026-08-09", "url": "https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-029-the-page-gutter.md" }, { "id": "ADR-030", "title": "Axis vocabulary: one name, one meaning", "status": "accepted 2026-10-17 (J-09) — migrated in `packages/ui`, Storybook, hydra, lente and proto; Lunántica and Sissificate (submodules) run on the deprecated aliases until slice S7", "date": "2026-10-16", "url": "https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-030-axis-vocabulary.md" }, { "id": "ADR-031", "title": "Tokens that cover the system: type roles, focus, ambient motion, control heights", "status": "accepted 2026-10-17 (audit slice S3, owner go \"Sigue con S3\")", "date": "2026-10-17", "url": "https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-031-token-coverage.md" }, { "id": "ADR-032", "title": "Themes compose by layers; brands are a checked layer", "status": "accepted 2026-10-17 (J-04, audit slice S4)", "date": "2026-10-17", "url": "https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-032-theme-layers-and-brand.md" }, { "id": "ADR-033", "title": "The material ships once, and the night is tokens", "status": "accepted 2026-10-17 (audit slice S5)", "date": "2026-10-17", "url": "https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-033-material-engineering.md" }, { "id": "ADR-034", "title": "Accessible names come from a labels provider", "status": "accepted 2026-10-17 (audit slice S6)", "date": "2026-10-17", "url": "https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-034-accessible-names-from-a-labels-provider.md" }, { "id": "ADR-035", "title": "Motion grammar: the gate before motion, slop by repetition, and what reduced motion keeps", "status": "accepted 2026-10-17 (J-13, slice G3)", "date": "2026-10-17", "url": "https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-035-motion-grammar.md" }, { "id": "ADR-036", "title": "Data visualization: colour roles, a grammar, and three components on plain SVG", "status": "accepted 2026-10-17 (J-13, slice G4)", "date": "2026-10-17", "url": "https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-036-data-visualization.md" }, { "id": "ADR-037", "title": "Continuity motion: a decelerating curve, a travelling indicator, view transitions and the SegmentedControl", "status": "accepted 2026-10-17 (Atlas premium pass)", "date": "2026-10-17", "url": "https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-037-continuity-motion.md" }, { "id": "ADR-038", "title": "Liquid Glass layers: glass for navigation and controls, a content material for everything read", "status": "accepted 2026-10-17 (J-16)", "date": "2026-10-17", "url": "https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-038-liquid-glass-layers.md" }, { "id": "ADR-039", "title": "The component premium pass: translucent fills, a selected register, quiet scroll, and a system-wide audit", "status": "accepted 2026-10-17 (J-17)", "date": "2026-10-17", "url": "https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-039-component-premium-pass.md" }, { "id": "ADR-040", "title": "The sidebar collapses by default and gives the page the room", "status": "accepted 2026-10-17 (J-18)", "date": "2026-10-17", "url": "https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-040-collapsible-sidebar.md" }, { "id": "ADR-041", "title": "The rail peeks instead of growing", "status": "accepted 2026-10-17 (J-23)", "date": "2026-10-17", "url": "https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-041-rail-peek.md" }, { "id": "ADR-042", "title": "The reader chooses the material: a transparency layer", "status": "accepted 2026-10-18 (J-31)", "date": "2026-10-18", "url": "https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-042-transparency-layer.md" }, { "id": "ADR-043", "title": "The default theme is monochrome", "status": "accepted 2026-10-18 (J-35)", "date": "2026-10-18", "url": "https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-043-monochrome-default.md" }, { "id": "ADR-044", "title": "Navigation is a rail that peeks", "status": "accepted 2026-10-18 (J-38)", "date": "2026-10-18", "url": "https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-044-rail-navigation.md" }, { "id": "ADR-045", "title": "A screen's controls pin and condense", "status": "accepted 2026-10-18 (J-49)", "date": "2026-10-18", "url": "https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-045-sticky-bars.md" }, { "id": "ADR-046", "title": "Markdown is painted with atoms, and apps fill its slots", "status": "proposed", "date": "2026-10-19", "url": "https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-046-markdown-molecule.md" } ], "taste": [ { "id": "T01", "title": "No dominant element", "area": "hierarchy", "scope": "both", "check": "review", "signal": "Several things on a screen compete at the same size and weight; squinting leaves no mass that leads.", "why": "The eye has nowhere to land and the screen reads as a list of equals (P11).", "instead": "One element leads each screen or region — the page title, the data that matters, or the primary action — and the rest step back through prominence and tone.", "related": [ "P11" ] }, { "id": "T02", "title": "More than one primary action per region", "area": "hierarchy", "scope": "both", "check": "review", "signal": "Two or more solid primary buttons side by side, or a primary on every card in a list.", "why": "When everything is primary nothing is; the accent stops marking the decision (P11).", "instead": "One `intent=\"primary\" emphasis=\"solid\"` per region; the others go to secondary, outline or ghost, or into an ActionGroup.", "related": [ "P11", "R02" ] }, { "id": "T03", "title": "Too many type sizes, too close together", "area": "type", "scope": "both", "check": "capture", "signal": "Six or more font sizes on one screen, or headings barely larger than body text.", "why": "Small steps read as noise, not hierarchy.", "instead": "Use the type roles only (display, heading-lg/md/sm, body-lg/body/body-sm, caption, eyebrow); five or fewer per screen, with visible jumps.", "related": [ "P11", "ADR-031" ] }, { "id": "T04", "title": "Template section sequence", "area": "layout", "scope": "marketing", "check": "review", "signal": "Hero, logo strip, three features, testimonial, pricing, closing call to action — in that order, because the template has them.", "why": "Sections that exist without a claim make every page the same page.", "instead": "One claim and its proof per section; delete sections without a claim; order them by the argument.", "related": [ "P10" ] }, { "id": "T05", "title": "Rows of identical icon-topped cards", "area": "layout", "scope": "both", "check": "review", "signal": "Three or four equal cards, each an icon in a rounded square above a title and two lines.", "why": "The most recognisable default layout; it says \"features\" without showing any.", "instead": "Show the thing — a list with real content, a split with a real picture or interface fragment, a table. Use cards when the items are objects the reader acts on.", "related": [ "P01", "P10" ] }, { "id": "T06", "title": "Everything centred", "area": "layout", "scope": "both", "check": "capture", "signal": "Most text on the page is centre-aligned, paragraphs included.", "why": "Centring everything removes the reading edge and flattens hierarchy.", "instead": "Two or three shared left edges for the page; centre at most one moment per screen; never centre a paragraph longer than three lines.", "related": [ "P11" ] }, { "id": "T07", "title": "Too many left edges", "area": "layout", "scope": "both", "check": "review", "signal": "Content starts at five or six different x positions down the page.", "why": "Items were placed one at a time; the page has no grid.", "instead": "Align to the container and its grid; reuse two or three anchor lines on purpose.", "related": [ "P06" ] }, { "id": "T08", "title": "Boxes inside boxes", "area": "layout", "scope": "both", "check": "review", "signal": "Cards inside cards inside panels; every group wrapped in its own bordered surface.", "why": "Compartments compete with content and multiply edges.", "instead": "One surface per layer. Inside it, separate with space (`stack`/`inline` tokens) and a tone step (`surface` axis), not another box. Vibrant panes never nest (ADR-027).", "related": [ "ADR-027", "P11" ] }, { "id": "T09", "title": "Thin or empty screens", "area": "layout", "scope": "both", "check": "capture", "signal": "A screen that is mostly empty, or a little content stretched over several screens.", "why": "Reads as unfinished; restraint is not the same as absence.", "instead": "Make the main element larger or remove the section; give empty states a real action (T37).", "related": [ "P10" ] }, { "id": "T10", "title": "The phone as a shrunken desktop", "area": "layout", "scope": "both", "check": "capture", "signal": "At 390 px the desktop layout is merely squeezed — tiny type, cramped rows, sideways scroll.", "why": "The phone is where most people read; a reduced desktop is a broken phone screen.", "instead": "Compose the phone screen on its own — first screen says what it is and offers its action; navigation in the bottom tab bar (PageShell); no horizontal scroll at 375 px.", "related": [ "P02", "C-21" ] }, { "id": "T11", "title": "Viewport units that hide content", "area": "layout", "scope": "both", "check": "lint", "signal": "Full-height sections sized with `100vh`, or fixed bars that cover content.", "why": "On phones `100vh` includes the browser chrome, so the bottom of the section hides behind it; fixed bars cover what they do not reserve space for.", "instead": "Use dynamic viewport units (`dvh`) and reserve space for every fixed bar (safe-area utilities).", "related": [ "P02" ] }, { "id": "T12", "title": "Headlines longer than two lines", "area": "type", "scope": "both", "check": "capture", "signal": "A heading wraps to three or more lines at any of the three review widths.", "why": "A long headline is a paragraph in disguise; it stops being scanned.", "instead": "Cut words before shrinking the size; keep statements as paragraphs; balanced wrapping, no orphan word.", "related": [ "P11" ] }, { "id": "T13", "title": "Eyebrows by default", "area": "type", "scope": "both", "check": "review", "signal": "A small uppercase kicker above every heading, or a pill badge above the hero, carrying no information.", "why": "The label became decoration; repeated, it is the generated look.", "instead": "Use the eyebrow role only when it carries information the heading does not (place, category, step); at most one per region.", "related": [ "P10", "ADR-031" ] }, { "id": "T14", "title": "Scattered tiny capitals", "area": "type", "scope": "both", "check": "capture", "signal": "Many small uppercase, letter-spaced labels around the screen; caps runs longer than three words.", "why": "Hard to read and visually noisy; it imitates \"detail\" instead of providing it.", "instead": "Sentence case at a readable role, next to what it describes; capitals only for the eyebrow role and short runs.", "related": [ "P02" ] }, { "id": "T15", "title": "Decorative numbering and meta", "area": "type", "scope": "both", "check": "review", "signal": "01 / 02 / 03 before sections that are not steps; version stamps, coordinates, \"est. 2024\", local time as ornament.", "why": "Gallery fashion that carries no information.", "instead": "Number only real sequences (Stepper, ordered lists); delete furniture text.", "related": [ "P10" ] }, { "id": "T16", "title": "One word styled differently in a headline", "area": "type", "scope": "both", "check": "review", "signal": "A single word in another colour, italic, serif or gradient inside a heading.", "why": "The fix that became the look; it splits the headline's voice.", "instead": "One face, one colour per heading. The serif voice is the display role, used once per page.", "related": [ "P11", "ADR-006" ] }, { "id": "T17", "title": "Grey body text", "area": "type", "scope": "both", "check": "review", "signal": "Paragraphs meant to be read set in the muted tone.", "why": "Reads unfinished and lowers contrast where reading happens.", "instead": "Body in `content-default`; `muted` only for secondary notes and metadata; quieter means a lower role or tone, never opacity.", "related": [ "R05", "P02" ] }, { "id": "T18", "title": "Text too small to read", "area": "type", "scope": "both", "check": "capture", "signal": "Reading text under 16 px, or blocks of text under 13 px.", "why": "Fails comfort before it fails WCAG.", "instead": "Body role for reading; caption and eyebrow only for short meta (the eyebrow's 11 px is the floor).", "related": [ "P02", "ADR-031" ] }, { "id": "T19", "title": "Justified or ragged-badly text", "area": "type", "scope": "both", "check": "lint", "signal": "Justified paragraphs, orphan words on headline last lines, paragraphs wider than about 75 characters.", "why": "Rivers, orphans and long measures slow reading.", "instead": "Left-aligned text, balanced headline wrapping, `max-w-prose` for long text.", "related": [ "P02" ] }, { "id": "T20", "title": "Accent everywhere", "area": "colour", "scope": "both", "check": "review", "signal": "The accent colour on headings, borders, bullets, icons and links at once; more than a small share of the screen.", "why": "An accent marks a decision; spread out, it marks nothing.", "instead": "The accent is for the primary action and focus; at most one other recurring element. Headings stay in ink.", "related": [ "P11", "ADR-028" ] }, { "id": "T21", "title": "Decorative gradients", "area": "colour", "scope": "both", "check": "lint", "signal": "Gradient text, gradient buttons, glows behind calls to action, violet-to-blue hero washes.", "why": "The first-generation look of generated interfaces; it also breaks contrast guarantees.", "instead": "Flat role colours. In Poesía the only gradient is the atmosphere ground, painted by the Atmosphere organism.", "related": [ "R04", "R05", "ADR-023" ] }, { "id": "T22", "title": "Material without purpose", "area": "material", "scope": "both", "check": "review", "signal": "A vibrant pane over a flat canvas, panes nested in panes, blur used as decoration, text placed on the sky.", "why": "Glass that has nothing behind it is a grey box; glass on glass muddies; words on the sky lose their protection.", "instead": "Vibrant panes on an Atmosphere ground, one pane per layer, type and actions on panes only (ADR-027); `solid` where the material does not carry meaning.", "related": [ "ADR-027", "ADR-022" ] }, { "id": "T23", "title": "Shadows on everything", "area": "material", "scope": "both", "check": "review", "signal": "Every resting card carries a drop shadow; glows under buttons.", "why": "Depth stops meaning anything when nothing is flat.", "instead": "Elevation by role — resting surfaces raised at most; shadows for what floats (popovers, dialogs, toasts) through the elevation tokens.", "related": [ "R04", "ADR-007" ] }, { "id": "T24", "title": "Softening with opacity", "area": "colour", "scope": "both", "check": "review", "signal": "Secondary text or icons made lighter with opacity instead of a tone.", "why": "Opacity drops contrast unpredictably over a ground and over the material.", "instead": "Use the `muted` or `subtle` content tones; opacity only for disabled (`opacity-disabled`).", "related": [ "R05", "R04" ] }, { "id": "T25", "title": "Decorative live signals", "area": "motion", "scope": "both", "check": "lint", "signal": "Pulsing dots, pinging badges, \"available now\" indicators that are not live data.", "why": "Attention-seeking loops with nothing to say (P10).", "instead": "Loops only for real progress or live data (Spinner, Skeleton, Progress); a static status Badge otherwise.", "related": [ "P10" ] }, { "id": "T26", "title": "Placeholders and fake interfaces", "area": "imagery", "scope": "both", "check": "review", "signal": "Grey boxes, \"image here\", abstract dashboards whose numbers do not add up.", "why": "Worse than no image: it tells the reader nothing is real.", "instead": "A real picture of the subject, a true-size fragment of the real interface with believable data, or type alone.", "related": [ "P10" ] }, { "id": "T27", "title": "Emoji as icons", "area": "imagery", "scope": "both", "check": "lint", "signal": "Emoji characters standing in for icons in buttons, navigation, lists or headings.", "why": "Inconsistent across platforms, not themable, unlabelled for assistive technology.", "instead": "An SVG through `Icon` (decorative, or with an accessible name); emoji only inside user content.", "related": [ "P02", "R04" ] }, { "id": "T28", "title": "Mixed icon styles", "area": "imagery", "scope": "both", "check": "review", "signal": "Outline and filled icons side by side, different stroke widths, cliché metaphors (rocket for launch).", "why": "One language per layer is what makes icons quiet.", "instead": "One family and stroke per hierarchy level, sized by the icon size axis.", "related": [ "P06" ] }, { "id": "T29", "title": "Clip-art decoration", "area": "imagery", "scope": "marketing", "check": "review", "signal": "Floating blobs, dot grids, wave dividers, isometric scenes, tilted framed screenshots.", "why": "Decoration that belongs to no subject.", "instead": "The Atmosphere is Poesía's ground; anything else drawn must be the subject's own thing, large, in one language.", "related": [ "P10", "ADR-023" ] }, { "id": "T30", "title": "Genre words", "area": "copy", "scope": "both", "check": "lint", "signal": "Unleash, supercharge, seamless, effortless, elevate, empower, next-gen, world-class, cutting-edge, game-changer, revolutionise.", "why": "Sentences any company could print unchanged say nothing about this one.", "instead": "Specific nouns and real numbers; test each sentence by asking whether a competitor could sign it.", "related": [ "P10" ] }, { "id": "T31", "title": "Formula sentences", "area": "copy", "scope": "both", "check": "lint", "signal": "\"Not just X, it's Y\", \"take your X to the next level\", \"the future of X\", three-word tricolons as headlines.", "why": "The construction is the generated voice, whatever the words.", "instead": "The plainest true sentence — what it is, what it does, for whom.", "related": [ "P10" ] }, { "id": "T32", "title": "Generic action labels", "area": "copy", "scope": "both", "check": "lint", "signal": "Buttons labelled Learn more, Click here, Submit, Get started.", "why": "The label should say what happens; a generic one makes the reader guess.", "instead": "Verb plus object in one to three words (\"Save changes\", \"Book a table\"); one label per intent across the product.", "related": [ "P02" ] }, { "id": "T33", "title": "Placeholder data", "area": "copy", "scope": "both", "check": "lint", "signal": "John Doe, Lorem ipsum, 1234567, 99.99%, identical avatars and dates.", "why": "Placeholder data hides layout problems real data would reveal.", "instead": "Realistic, varied names, lengths and numbers — including the longest real value.", "related": [ "P10" ] }, { "id": "T34", "title": "Invented proof", "area": "copy", "scope": "marketing", "check": "review", "signal": "Logo walls, ratings, quotes or \"10,000+ teams\" with no source.", "why": "Untrue claims; also the most recognisable generated filler.", "instead": "True facts only (price, place, inclusions); clearly marked samples to replace when the real proof is missing.", "related": [ "P07" ] }, { "id": "T35", "title": "Hyped or cute tone in system messages", "area": "copy", "scope": "both", "check": "review", "signal": "Exclamation marks in confirmations, jokes in errors, Title Case headings, passive voice.", "why": "The interface should sound like a capable colleague, not an advert.", "instead": "Plain, active, sentence case; errors say what happened and how to fix it.", "related": [ "P02" ] }, { "id": "T36", "title": "The wrong waiting state", "area": "states", "scope": "product", "check": "review", "signal": "A spinner where the layout is known, a blank screen while loading, content jumping when it arrives.", "why": "The wait feels longer and the layout shifts.", "instead": "Skeleton in the shape of the content for waits over about a second; reserve the space; Spinner only inside controls.", "related": [ "P02" ] }, { "id": "T37", "title": "Empty states with nothing to do", "area": "states", "scope": "product", "check": "review", "signal": "An empty list or dashboard that only says \"No data\".", "why": "The first run is where the product explains itself.", "instead": "EmptyState with what will appear here and one action to create the first item.", "related": [ "P08" ] }, { "id": "T38", "title": "Dead or hidden interactions", "area": "states", "scope": "both", "check": "lint", "signal": "Links to `#`, actions reachable only on hover, missing focus, no active state in navigation.", "why": "Keyboard, touch and screen-reader users cannot reach what the mouse can.", "instead": "Real destinations; every hover affordance has a tap and keyboard equivalent; the shared focus ring; NavItem `active`.", "related": [ "P02", "R14" ] }, { "id": "T39", "title": "Uniform motion everywhere", "area": "motion", "scope": "both", "check": "lint", "signal": "The same fade-and-rise on every block, stagger on every list, hover scale on every card, bounce on utility controls, `transition: all`, entering from scale 0, ease-in on interface motion.", "why": "Motion applied by default says nothing about cause and effect, and some of it reflows the layout.", "instead": "Motion by frequency and purpose on the motion tokens (G3); transform and opacity only; ease-out to enter, never ease-in; press feedback, not hover lift.", "related": [ "P10", "ADR-031" ] } ], "dataviz": { "notAChart": [ { "data": "A single current value, maybe with a trend", "use": "MetricCard (value, delta, optional sparkline)" }, { "data": "A handful of headline numbers", "use": "A row of MetricCards" }, { "data": "The one number a screen leads with", "use": "A hero figure in the sans display role, one per view" }, { "data": "One ratio against a limit", "use": "Progress or a meter" }, { "data": "More than about seven classes that all carry meaning", "use": "A table (DataTable), with a chart beside it if the shape matters" } ], "forms": [ { "job": "Compare magnitude, low to high", "form": "bar or column; heatmap for a grid", "colour": "sequential, or one series colour", "avoid": "time series; proportions" }, { "job": "Trend over time", "form": "line; area for a single series", "colour": "one series colour, or categorical for a few series", "avoid": "fewer than four points; more than six series; no time axis" }, { "job": "Tell distinct series apart", "form": "grouped or stacked bar, multi-line", "colour": "categorical, in slot order", "avoid": "more series than the ladder allows" }, { "job": "One series is the point, the rest are context", "form": "emphasis — one series in colour, the rest in the neutral tone", "colour": "one series colour plus neutral", "avoid": "categorical colour on every series" }, { "job": "Above or below a baseline; delta to a target", "form": "diverging bar, or a line against the baseline", "colour": "diverging", "avoid": "red and green alone" }, { "job": "Part to whole", "form": "stacked bar (horizontal for many or long names); a donut only for five slices or fewer with a dominant one", "colour": "categorical", "avoid": "near-equal slices; precise reading from angles" }, { "job": "Ordered-scale share (agree to disagree, sentiment)", "form": "diverging stacked bar, centred on the neutral", "colour": "diverging", "avoid": "categorical colour on an ordered scale" }, { "job": "Before and after per item", "form": "dumbbell", "colour": "one series colour in two steps", "avoid": "two separate bar charts" }, { "job": "Distribution or spread", "form": "histogram, box plot; scatter for two continuous variables (twenty points or more)", "colour": "one series colour; at most three categorical series in a scatter", "avoid": "scatter for categorical data" }, { "job": "Intensity over two dimensions (hour by day)", "form": "heatmap with a numeric legend", "colour": "sequential", "avoid": "a rainbow scale" } ], "colourJobs": { "categorical": { "tokens": "series-1 … series-8", "rule": "Identity. Assigned in slot order, never cycled, never by rank; a series keeps its colour when a filter removes others. A ninth series folds into \"Other\", small multiples, or a second encoding — never a generated hue." }, "ordinal": { "tokens": "scale-1 … scale-5", "rule": "Order (funnel stage, tier, bucket). One hue, monotone lightness. Use it whenever reordering the categories would change the meaning." }, "sequential": { "tokens": "scale-1 … scale-5", "rule": "Magnitude. One hue, light to dark by day, dark to light by night. The safe default." }, "diverging": { "tokens": "diverging-below-3 … diverging-neutral … diverging-above-3", "rule": "Polarity. Two hues and a neutral midpoint, equal steps per arm; never a hue at the midpoint." }, "status": { "tokens": "feedback and status roles (success, warning, danger, neutral)", "rule": "State, with reserved meaning, always with an icon and a label. When a series means good or bad it wears status roles; when it is just a series it wears categorical — never both in one chart." } }, "seriesLadder": [ { "count": "1 to 3", "treatment": "Colour alone is comfortable; label directly. Forms where any two marks can touch (scatter, bubble, maps, small multiples) stop here." }, { "count": 4, "treatment": "Bars, stacks and lines stay safe; direct labels become mandatory." }, { "count": "5 to 6", "treatment": "Soft cap; legend, or small multiples." }, { "count": "7 to 8", "treatment": "The ceiling. Past it, fold the tail into \"Other\", facet, or add a second encoding (shape)." } ], "labels": [ "A legend whenever there are two or more series; none for one (the title names it).", "Direct labels are selective — the endpoint, the extreme, the series the story is about — never a number on every point.", "Text never wears a series colour; values, labels and legends use content tones, and a coloured key beside them carries the identity.", "A label that does not fit inside its mark moves outside it or into the tooltip; it is never clipped.", "Axis ticks are round numbers, compacted from a thousand (1K, 2K); units on the axis.", "Large standalone figures use proportional numerals; columns of numbers use tabular numerals." ], "interaction": [ { "Tooltips enhance, never gate": "every value is also reachable through labels or the table view." }, "Lines and areas take a crosshair that snaps to the nearest data position and lists every series at that position; bars and cells are their own hit targets.", "Hit targets are larger than the mark (at least the WCAG 2.2 target size); dense scatter uses nearest-point.", "The same details on keyboard focus as on hover; marks are reachable by keyboard.", "Filters sit in one row above the charts they scope, date range first; a refetch keeps the last render, dimmed, instead of a skeleton.", "Series and category names are untrusted data, inserted as text, never as markup." ], "accessibility": [ "A table view (or DataTable) of the same data is always reachable.", "Identity is never colour alone (legend, direct labels, or texture).", "A text summary or accessible name states the chart's one insight.", { "Charts are readable at once; they do not draw themselves in on arrival (ADR-035 gate": "decoration), and live updates respect reduced motion." }, { "Empty, loading and error states are designed": "what will appear, a skeleton in the chart's shape, a retry." }, "Night values are their own steps, validated on the night surface, not an automatic inversion." ], "never": [ "Two y-axes on one chart. Two measures of different scale are two charts, small multiples, or indexed to a common base.", "A rainbow scale, or a hue at a diverging midpoint.", "Colour assigned by rank, or repainted when a filter changes the series.", "3D, gradients, shadows or glows on data marks.", "Pie or donut with more than five slices or near-equal slices.", "A chart for a single number." ] }, "product": { "levers": { "scheme": "Which colour scheme the product opens in — day or night — before the reader chooses (ADR-032).", "density": "default, or desktop density for information-dense work (ADR-032).", "contrast": "The target above AA (R05) — AA, or AAA where the reader may be vulnerable or the domain regulated.", "atmosphere": "How much sky the working screens carry — full, quiet (reading rooms), or still — and whether it drifts (ADR-023, ADR-031).", "material": "vibrant panes by default; solid for instruments, dense tables and charts that need a flat ground (ADR-027).", "display": "Whether the serif display voice appears (once per page) or the product stays in the sans.", "motion": "The lens of the motion gate (ADR-035) — restraint (frequent use, tools), polish (product), or play (rare moments, learning).", "brand": "The brand layer's hues (BRAND.md) — the only place a product chooses colour, checked for contrast." }, "profiles": [ { "id": "tool", "for": "Productivity tools, editors, back offices, content management", "scheme": "day", "density": "desktop on desktop screens", "contrast": "AA", "atmosphere": "quiet, still on working screens", "material": "vibrant chrome, solid instruments", "display": "none on working screens", "motion": "restraint", "must_have": [ "keyboard paths and shortcuts", "undo for destructive actions", "empty states that teach" ], "avoid": [ "T01", "T05", "T09", "T39" ] }, { "id": "data", "for": "Dashboards, analytics, monitoring, status pages", "scheme": "night", "density": "desktop", "contrast": "AA", "atmosphere": "still", "material": "solid instruments, vibrant chrome only", "display": "none; a sans hero figure leads", "motion": "restraint", "must_have": [ "filters in one row above the charts", "a table view for every chart", "live values without flashing", "export" ], "avoid": [ "T03", "T21", "T25", "T26" ] }, { "id": "money", "for": "Banking, payments, fintech, wallets, trading", "scheme": "day", "density": "default", "contrast": "AAA for amounts and actions", "atmosphere": "quiet, still", "material": "vibrant chrome, solid for statements and forms", "display": "none in flows; allowed on the landing", "motion": "restraint", "must_have": [ "every fee and amount visible before confirming", "confirmation and undo where possible", "tabular numerals", "plain security states" ], "avoid": [ "T21", "T30", "T34", "T35" ] }, { "id": "care", "for": "Health, mental health, wellbeing, beauty and care services", "scheme": "day", "density": "default", "contrast": "AAA", "atmosphere": "quiet, slow drift", "material": "vibrant, soft", "display": "once per page", "motion": "polish, gentle; nothing pulsing", "must_have": [ "calm copy", "large reading text", "safe defaults", "an obvious way to get help" ], "avoid": [ "T25", "T35", "T39" ] }, { "id": "commerce", "for": "Shops, marketplaces, bookings, luxury goods", "scheme": "day", "density": "default", "contrast": "AA", "atmosphere": "full on browsing screens, quiet at checkout", "material": "vibrant", "display": "once per page on browsing screens", "motion": "polish", "must_have": [ "real product pictures", "price and availability next to the action", "a short checkout", "trust at payment" ], "avoid": [ "T05", "T26", "T32", "T34" ] }, { "id": "reading", "for": "Editorial, documentation, courses, long-form content, divination and interpretation texts", "scheme": "day, night available", "density": "default, generous measure", "contrast": "AA", "atmosphere": "quiet reading rooms (the reading sheet)", "material": "vibrant reading sheets", "display": "the article title", "motion": "restraint", "must_have": [ "readable measure", "reading progress or table of contents for long text", "typographic quality" ], "avoid": [ "T12", "T17", "T18", "T19" ] }, { "id": "community", "for": "Social, creators, messaging, communities, adult content platforms", "scheme": "night", "density": "default", "contrast": "AA", "atmosphere": "full drift on the home, quiet in conversations", "material": "vibrant", "display": "profiles and the home", "motion": "polish; play for rare moments (a first post, a milestone)", "must_have": [ "privacy controls in reach", "clear consent and visibility states", "moderation cues", "real people's content first" ], "avoid": [ "T25", "T26", "T33", "T39" ] }, { "id": "learning", "for": "Learning products, kids, gamified progress", "scheme": "day", "density": "default", "contrast": "AA", "atmosphere": "full", "material": "vibrant", "display": "section openers", "motion": "play for rewards and progress, restraint in exercises", "must_have": [ "visible progress", "encouraging feedback", "no dark patterns", "large targets" ], "avoid": [ "T35", "T36", "T37" ] }, { "id": "studio", "for": "Creative studios, media generation and editing, portfolios", "scheme": "night", "density": "desktop for editing panels", "contrast": "AA", "atmosphere": "still behind the canvas, full on the landing", "material": "solid around the work, vibrant chrome", "display": "the landing and project titles", "motion": "restraint in the editor, polish elsewhere", "must_have": [ "the work is the largest thing on screen", "non-destructive editing", "clear cost and progress for long jobs" ], "avoid": [ "T22", "T26", "T29" ] }, { "id": "developer", "for": "Developer tools, APIs, consoles, status of services", "scheme": "night", "density": "desktop", "contrast": "AA", "atmosphere": "still", "material": "solid instruments", "display": "none", "motion": "restraint", "must_have": [ "copyable values", "discoverable endpoints", "explicit limits and errors", "code in the mono face" ], "avoid": [ "T15", "T21", "T30" ] }, { "id": "landing", "for": "Marketing and launch pages", "scheme": "the product's", "density": "default", "contrast": "AA", "atmosphere": "full, drifting", "material": "vibrant", "display": "the hero", "motion": "polish, one signature moment", "must_have": [ "one claim and its proof per section", "the real product shown", "one primary action per section" ], "avoid": [ "T04", "T05", "T29", "T30", "T31", "T34" ] } ], "delivery": [ "Works at 375, 768, 1024 and 1440 px, and in landscape on a phone; no horizontal scroll; nothing under fixed bars.", "Touch targets of at least 44 px with room between them; pointer targets of at least 24 px.", "Every field has a visible label; errors appear on leaving the field, say what to do, and a failed submit focuses a linked summary (ErrorSummary).", "Buttons that start work disable and show progress until it ends; destructive actions confirm and, where possible, undo.", "Loading has the shape of the content, empty states offer the first action, errors offer a way out.", "Colour is never the only signal; focus is visible and never hidden by sticky bars.", "Controls the reader needs while the content scrolls (filters, search, a view switch, section tabs; a selection's actions) stay in reach in a pinned, condensed bar — one per edge (ADR-045).", "Numbers, dates and money are formatted for the locale; columns of numbers use tabular numerals.", "Night and more contrast are checked as their own themes, not assumed.", "Reduced motion and the largest text size leave every task possible." ] }, "motion": { "registers": { "interaction": { "tempo": "fast | default | slow (the duration tokens)", "purpose": "Explain a change of state; enter toward where the element belongs." }, "ambient": { "tempo": "seconds to minutes; nothing under six seconds; crossfades of at least 0.8 seconds", "purpose": "The atmosphere's drift and breath. Never zoom, spin or parallax in a loop; never attention-seeking." } }, "gate": [ { "id": "G1", "question": "How often is it triggered?", "answer": "Rare (onboarding, a first success, about monthly) may be expressive:\nslow duration, emphasized easing. Occasional (daily) is quiet and\nquick: fast or default. Frequent (typing, list navigation, sorting,\nfiltering, many times per session) does not animate: the change is\ninstant.\n" }, { "id": "G2", "question": "Was it started from the keyboard?", "answer": "Keyboard-driven changes (arrow navigation, shortcuts, typing) are instant. A shortcut that opens a surface may open it on the surface's recipe; moving inside it does not animate." }, { "id": "G3", "question": "What is it for?", "answer": "Feedback (a press, a state flip), orientation (where something came\nfrom or went), or continuity (content arriving, leaving, resizing).\nAnything else is decoration and goes. Delight is allowed only for\nrare moments.\n" }, { "id": "G4", "question": "Does it survive the tenth repetition?", "answer": "If it would annoy on the tenth time, make it faster, smaller, or remove it." }, { "id": "G5", "question": "What is lost without it?", "answer": "If removing it leaves the reader unsure what happened, it is functional and must survive reduced motion as a non-motion cue. Otherwise it is decorative and is dropped under reduced motion." } ], "recipes": [ { "class": "hover, focus, state change", "duration": "fast", "easing": "standard", "properties": [ "colour", "background", "border", "opacity", "shadow" ], "note": "Never instant (a colour snap reads as broken), never a layout change." }, { "class": "press", "duration": "fast", "easing": "standard", "properties": [ "scale" ], "note": "Button-shaped controls scale to 0.98 while pressed (ADR-005). Surfaces with content do not shrink." }, { "class": "compact overlay (tooltip, popover, dropdown menu)", "duration": "fast", "easing": "standard", "properties": [ "opacity", "scale" ], "note": "Scale from 0.95, from the trigger's side (transform origin at the trigger). Same recipe in and out." }, { "class": "tray overlay", "duration": "default", "easing": "standard", "properties": [ "opacity", "translate" ], "note": "A short travel (about 4 px) toward its resting place." }, { "class": "dialog", "duration": "default", "easing": "standard", "properties": [ "opacity", "scale" ], "note": "Scale from 0.96. Symmetric exit (ADR-018)." }, { "class": "drawer, sheet", "duration": "default", "easing": "standard", "properties": [ "opacity", "translate" ], "note": "From its edge. Symmetric exit (ADR-018)." }, { "class": "toast", "duration": "fast", "easing": "standard", "properties": [ "opacity", "translate" ], "note": "A momentary acknowledgement, not an arrival." }, { "class": "inline feedback (field error, inline alert, validation message)", "duration": "fast", "easing": "standard", "properties": [ "opacity" ], "note": "Fades in where it will stay; the layout change itself is not animated." }, { "class": "tab panel", "duration": "instant", "easing": "none", "properties": [], "note": "The panel swaps at once and the selection indicator travels; the old panel is gone before the new one paints, so a fade-in reads as an empty frame (J-37)." }, { "class": "content swap (loading to content, icon swap)", "duration": "fast", "easing": "standard", "properties": [ "opacity" ], "note": "Crossfade; the skeleton has the shape of the content, so nothing jumps." }, { "class": "selection indicator (tab underline, segmented thumb)", "duration": "default", "easing": "standard", "properties": [ "clip-path" ], "note": "One shape travels to the chosen option (ADR-037). Pointer choices travel; keyboard moves, first paint and resizes are instant." }, { "class": "page change in an app frame (view transition)", "duration": "default", "easing": "standard", "properties": [ "opacity", "translate" ], "note": "The page crossfades on fast, the new content rises 4 px, the current navigation pill travels to the new item (ADR-037, startViewTransition)." }, { "class": "reveal (theme switch)", "duration": "slow", "easing": "emphasized", "properties": [ "clip-path" ], "note": "The new state opens as a circle from its trigger. Rare, so expressive (G1); instant under reduced motion (ADR-037)." }, { "class": "surface leaving the canvas (route change, hero swap)", "duration": "slow", "easing": "emphasized", "properties": [ "opacity", "translate" ], "note": "The only use of the emphasized easing (ADR-018)." }, { "class": "progress and live data", "duration": "loop", "easing": "linear or standard", "properties": [ "transform", "opacity" ], "note": "Loops only where work is really happening (Spinner, Progress, Skeleton)." } ], "rules": [ { "id": "MR1", "rule": "Animate transform, opacity, filter and clip-path. Never width, height, margin, padding, top or left (they reflow every frame)." }, { "id": "MR2", "rule": "Never start from scale 0. Overlays start at 0.95 to 0.96; nothing starts below 0.9." }, { "id": "MR3", "rule": "Never ease-in for interface motion, and never the browser's default easing; use the standard or emphasized easing tokens." }, { "id": "MR4", "rule": "Overlays grow from their trigger (transform origin at the trigger's side), not from their centre." }, { "id": "MR5", "rule": "Sheets and panels leave on the same recipe that brought them in (symmetric exits, ADR-018). Inline content that disappears because the reader removed it may simply go." }, { "id": "MR6", "rule": "One easing family per register; durations come from the tokens only. A new duration is a token proposal, not a literal." }, { "id": "MR7", "rule": "Interruptible motion uses transitions, so a reversal mid-flight retargets. Exit keyframes exist only where a primitive needs them to delay unmounting (ADR-018)." }, { "id": "MR8", "rule": "No bounce or overshoot on utility controls (menus, toggles, dialogs, settings, errors)." }, { "id": "MR9", "rule": "will-change only on what is about to move, never globally; keep continuously animated layers few." } ], "slop": [ { "id": "MS1", "pattern": "Looping attention signals (pulsing dots, breathing calls to action, ping badges)", "threshold": "any instance that is not real progress or live data", "taste": "T25" }, { "id": "MS2", "pattern": "Hover scale on many elements", "threshold": "three or more components with the same hover scale (one primary floating action, or a draggable thumb, is fine)", "taste": "T39" }, { "id": "MS3", "pattern": "The same entrance on everything (identical fade-and-rise)", "threshold": "four or more components sharing one entrance", "taste": "T39" }, { "id": "MS4", "pattern": "Staggered lists", "threshold": "two or more staggered lists in one view", "taste": "T39" }, { "id": "MS5", "pattern": "Bounce on utility controls", "threshold": "any instance", "taste": "T39" }, { "id": "MS6", "pattern": "Motion on mount for static content (headings, paragraphs, navigation)", "threshold": "any instance without a purpose from the gate", "taste": "T39" }, { "id": "MS7", "pattern": "Blur entrances everywhere", "threshold": "three or more components sharing one blur entrance, or blur over reading text", "taste": "T39" } ], "reducedMotion": { "sources": "The `reduced-motion` theme layer (`data-motion=\"reduce\"`) and the operating system preference apply the same contract; the OS always wins over a theme (ADR-032).", "keep": "State changes still land, instantly or as a slow crossfade; anything whose removal would leave the reader unsure what happened is replaced by a non-motion cue (colour, outline, text), never deleted.", "drop": "Travel, scale, parallax, ambient loops (the sky goes still, not dead) and every decorative flourish.", "final_state": "Every animation's end state is reachable without it; nothing is hidden until an animation runs." }, "divergences": [ { "topic": "Exit weight", "source": "Exits should be lighter and faster than entrances.", "poesia": "Sheets and panels exit symmetrically; asymmetric exits read as a flicker.", "decision": "ADR-018 (owner, motion follow-up)" }, { "topic": "Press scale", "source": 0.97, "poesia": "0.98 on button-shaped controls only.", "decision": "ADR-005" }, { "topic": "Duration ceiling", "source": "Under 300 ms for productivity interfaces, 180 ms ideal.", "poesia": "fast 150 ms and default 250 ms for interaction; slow 400 ms only for large surfaces and rare moments.", "decision": "ADR-018, ADR-031" }, { "topic": "Width animation for the sidebar morph", "source": "Never animate layout properties.", "poesia": "The sidebar morph (panel to rail) animates width, a single surface on an occasional action; accepted until a transform-based morph exists. Only the labelled-panel opt-in morphs; the default rail never grows (ADR-044).", "decision": "ADR-018 (accepted exception, revisited in ADR-035)" } ] }, "counts": { "atom": 26, "molecule": 65, "organism": 15 } }, "needs": [ { "need": "Primary CTA", "answer": "`Button intent=\"primary\" emphasis=\"solid\"`", "components": [ "Button" ] }, { "need": "Destructive action", "answer": "`Button intent=\"danger\" emphasis=\"solid\"`", "components": [ "Button" ] }, { "need": "Quiet secondary action", "answer": "`Button intent=\"neutral\" emphasis=\"ghost\"`", "components": [ "Button" ] }, { "need": "Icon-only button", "answer": "`IconButton`", "components": [ "IconButton" ] }, { "need": "Link styled as a button", "answer": "`Link className={buttonVariants({ intent, variant, size })}`", "components": [ "Link" ] }, { "need": "Page header / section title", "answer": "`PageHeader` / `SectionHeader`", "components": [ "PageHeader", "SectionHeader" ] }, { "need": "Content card", "answer": "`Card`", "components": [ "Card" ] }, { "need": "KPI / metric", "answer": "`MetricCard`", "components": [ "MetricCard" ] }, { "need": "Pricing plan", "answer": "`PlanCard` or `PricingOption`", "components": [ "PlanCard", "PricingOption" ] }, { "need": "Empty / loading state", "answer": "`EmptyState` / `LoadingState` or `Skeleton`", "components": [ "EmptyState", "LoadingState", "Skeleton" ] }, { "need": "Inline spinner", "answer": "`Spinner`", "components": [ "Spinner" ] }, { "need": "Alert / banner", "answer": "`Alert tone=\"info|success|warning|danger|neutral\"`", "components": [ "Alert" ] }, { "need": "Ephemeral toast", "answer": "`Toast`", "components": [ "Toast" ] }, { "need": "Tooltip / popover / contextual menu", "answer": "`Tooltip` / `Popover` / `DropdownMenu`", "components": [ "Tooltip", "Popover", "DropdownMenu" ] }, { "need": "Confirmation modal / generic modal", "answer": "`Dialog` + `ConfirmDialogContent` / `Dialog`", "components": [ "Dialog", "ConfirmDialogContent" ] }, { "need": "Side panel", "answer": "`Drawer` or `Sheet`", "components": [ "Drawer", "Sheet" ] }, { "need": "Tabs / select / autocomplete", "answer": "`Tabs` / `Select` / `Combobox` or `SearchField`", "components": [ "Tabs", "Select", "Combobox", "SearchField" ] }, { "need": "One of a few values, all in view (range, view mode)", "answer": "`SegmentedControl` (two to five options; more → `Select`)", "components": [ "SegmentedControl", "Select" ] }, { "need": "Field with label + helper + error", "answer": "`Field` + `Input`/`Textarea`/`Select`", "components": [ "Field", "Input", "Textarea", "Select" ] }, { "need": "Group of fields", "answer": "`FormSection` or `InputGroup`", "components": [ "FormSection", "InputGroup" ] }, { "need": "Complex validated form", "answer": "`Form` organism (RHF + Zod)", "components": [ "Form" ] }, { "need": "Binary toggle / checkbox / radio group", "answer": "`Switch` (in `SettingsField` with label) / `Checkbox` / `ChoiceGroup` with `Radio`", "components": [ "Switch", "SettingsField", "Checkbox", "ChoiceGroup", "Radio" ] }, { "need": "OTP / 2FA code", "answer": "`InputOtp` (molecule)", "components": [ "InputOtp" ] }, { "need": "Date field / file drop / slider", "answer": "`DateField` / `FileDropzone` / `Slider`", "components": [ "DateField", "FileDropzone", "Slider" ] }, { "need": "Property list / data row / list item", "answer": "`PropertyList` / `DataRow` / `ListItem`", "components": [ "PropertyList", "DataRow", "ListItem" ] }, { "need": "Row that opens a page (settings-list disclosure)", "answer": "`ListItem href` (whole row is the link, trailing chevron)", "components": [ "ListItem" ] }, { "need": "Notification / timeline / activity item", "answer": "`NotificationItem` / `TimelineItem` / `ActivityItem`", "components": [ "NotificationItem", "TimelineItem", "ActivityItem" ] }, { "need": "Notification center", "answer": "`NotificationCenter`", "components": [ "NotificationCenter" ] }, { "need": "Feed card / infinite feed", "answer": "`FeedCard` / `Feed`", "components": [ "FeedCard", "Feed" ] }, { "need": "Threaded comments", "answer": "`CommentsThread`", "components": [ "CommentsThread" ] }, { "need": "Chat message / reactions", "answer": "`ChatBubble` / `ReactionBar`", "components": [ "ChatBubble", "ReactionBar" ] }, { "need": "Auth flow", "answer": "`AuthCard`", "components": [ "AuthCard" ] }, { "need": "Marketing / onboarding hero", "answer": "`Hero`", "components": [ "Hero" ] }, { "need": "App frame / navigation", "answer": "**The rail that peeks (ADR-044) — the default and the recommendation.** `PageShell` (defaults: `sidebarMode=\"rail\"`, `sidebarPresentation=\"inset\"`, `mobileNav=\"tabs\"`) + `SidebarSection aria-label` + ONE untitled `NavGroup`: home, search, the rooms, settings — same size, same gap. Wrap every `NavItem` in `PageShell.RailPeek` and compose its panel with `PageShell.PeekHeader` / `PeekFacts` / `PeekLinks`. Search is a button row opening `CommandMenu` (⌘K); settings' peek holds the quick controls; phones get `PageShell.MobileTabBar` (≤ 5). No `TopBar` in an app frame. Opt-ins only when a product needs them: the labelled panel (`sidebarMode=\"auto\"`, ⌘\\\\ collapse, ADR-040), `island`/`column` (ADR-025), the bubble (`mobileNav=\"bubble\"`)", "components": [ "PageShell", "SidebarSection", "NavGroup", "NavItem", "PeekFacts", "PeekLinks", "CommandMenu", "TopBar" ] }, { "need": "Controls that must stay in reach while the screen scrolls (filters, search, a view switch, section tabs) — or a selection's / a form's actions", "answer": "`PageShell.StickyBar` (ADR-045) under the `PageHeader`, `edge=\"bottom\"` for actions: at rest part of the page; pinned, it condenses onto glass and carries the page title small. One bar per edge; never hides focus", "components": [ "PageShell", "PageHeader" ] }, { "need": "Ground behind glass", "answer": "`Atmosphere`", "components": [ "Atmosphere" ] }, { "need": "Command palette", "answer": "`CommandMenu`", "components": [ "CommandMenu" ] }, { "need": "Table", "answer": "`DataTable`, or `TableHeader` + `TableRow` + `TablePagination`", "components": [ "DataTable", "TableHeader", "TableRow", "TablePagination" ] }, { "need": "Filters / pagination / stepper", "answer": "`FilterBar` / `Pagination` / `Stepper`", "components": [ "FilterBar", "Pagination", "Stepper" ] }, { "need": "Toolbar / split action", "answer": "`Toolbar` or `ActionGroup` / `SplitAction`", "components": [ "Toolbar", "ActionGroup", "SplitAction" ] }, { "need": "A trend in a tile or a row", "answer": "`Sparkline` (in `MetricCard`'s `trend` slot)", "components": [ "Sparkline", "MetricCard" ] }, { "need": "Names ranked by a value (top pages, products)", "answer": "`BarList`", "components": [ "BarList" ] }, { "need": "A chart (trend, comparison, part to whole)", "answer": "`Chart` with the `form` the data's job names (`dataviz.yaml`); a single number is a `MetricCard`, many classes a `DataTable`", "components": [ "Chart", "MetricCard", "DataTable" ] }, { "need": "Media viewer / composer / profile", "answer": "`MediaLightbox` / `Composer` / `ProfileHeader`", "components": [ "MediaLightbox", "Composer", "ProfileHeader" ] }, { "need": "Responsive grid / max-width container", "answer": "`Grid` / `Container`", "components": [ "Grid", "Container" ] }, { "need": "Content that overflows one axis (a strip of options, a long list in a pane)", "answer": "`ScrollArea` (edge fades, no heavy scrollbar)", "components": [ "ScrollArea" ] }, { "need": "Avatar / badge / separator / icon", "answer": "`Avatar` / `Badge` / `Separator` / `Icon`", "components": [ "Avatar", "Badge", "Separator", "Icon" ] }, { "need": "Text / heading / helper / code / shortcut", "answer": "`Text` / `Heading` / `Description` / `Code` / `Kbd`", "components": [ "Text", "Heading", "Description", "Code", "Kbd" ] }, { "need": "Markdown a model or an editor wrote (an answer, an article body)", "answer": "`Markdown` (ADR-046): atoms only, never `dangerouslySetInnerHTML`; app pieces (routing, glossary, chips) through `renderLink` / `renderMarker` / `renderText`, link policy through `allowLink`", "components": [ "Markdown" ] }, { "need": "Screen-reader-only text", "answer": "`VisuallyHidden`", "components": [ "VisuallyHidden" ] } ], "components": [ { "id": "avatar", "name": "Avatar", "level": "atom", "status": "stable", "purpose": "A person or entity at a glance — a photo, or initials when there is none.", "description": "Image-with-fallback identity primitive. Composes `@radix-ui/react-avatar` so the fallback shows while the image loads (and stays if the image errors). `alt` is required; pass `alt=\"\"` only when the avatar is decorative and the surrounding text already names the entity.", "role": "content", "import": "@rrios-forge/ui/atoms/avatar", "exports": [ "Avatar", "avatarKindFromShape", "avatarVariants", "AVATAR_KINDS", "AVATAR_SHAPES", "AVATAR_SIZES" ], "source": "packages/ui/src/atoms/avatar", "axes": [ { "axis": "size", "part": null, "values": [ "sm", "md", "lg", "xl" ], "default": "md", "meaning": "Ergonomic scale, in three families (control, text, container)." }, { "axis": "kind", "part": null, "values": [ "person", "entity" ], "default": null, "meaning": "What an avatar stands for — a person (round) or an entity such as a workspace or brand (rounded square) (ADR-039)." }, { "axis": "shape", "part": null, "values": [ "circle", "rounded" ], "default": null, "meaning": "Geometry, where geometry is the meaning." } ], "needs": [ { "need": "Avatar / badge / separator / icon", "answer": "`Avatar` / `Badge` / `Separator` / `Icon`" } ], "patterns": [], "a11yExceptions": [], "decisions": [ { "id": "ADR-013", "title": "PageShell: mobile-nav polymorphism" }, { "id": "ADR-014", "title": "PageShell: Apple Mail / macOS Big Sur visual register" } ], "stories": [ { "name": "Playground", "id": "components-atoms-avatar--playground", "interaction": false, "snapshots": [ "dark", "light" ], "skipsSnapshot": false, "docs": "/?path=/story/components-atoms-avatar--playground", "frame": "/iframe.html?id=components-atoms-avatar--playground&viewMode=story" }, { "name": "Sizes", "id": "components-atoms-avatar--sizes", "interaction": false, "snapshots": [ "dark", "light" ], "skipsSnapshot": false, "docs": "/?path=/story/components-atoms-avatar--sizes", "frame": "/iframe.html?id=components-atoms-avatar--sizes&viewMode=story" }, { "name": "Kinds", "id": "components-atoms-avatar--kinds", "interaction": false, "snapshots": [ "dark", "light" ], "skipsSnapshot": false, "docs": "/?path=/story/components-atoms-avatar--kinds", "frame": "/iframe.html?id=components-atoms-avatar--kinds&viewMode=story" }, { "name": "With image", "id": "components-atoms-avatar--with-image", "interaction": false, "snapshots": [ "dark", "light" ], "skipsSnapshot": false, "docs": "/?path=/story/components-atoms-avatar--with-image", "frame": "/iframe.html?id=components-atoms-avatar--with-image&viewMode=story" }, { "name": "Fallback", "id": "components-atoms-avatar--fallback", "interaction": false, "snapshots": [ "dark", "light" ], "skipsSnapshot": false, "docs": "/?path=/story/components-atoms-avatar--fallback", "frame": "/iframe.html?id=components-atoms-avatar--fallback&viewMode=story" }, { "name": "Group", "id": "components-atoms-avatar--group", "interaction": false, "snapshots": [ "dark", "light" ], "skipsSnapshot": false, "docs": "/?path=/story/components-atoms-avatar--group", "frame": "/iframe.html?id=components-atoms-avatar--group&viewMode=story" } ], "storyFile": "tooling/storybook/stories/components/atoms/avatar.stories.tsx" }, { "id": "badge", "name": "Badge", "level": "atom", "status": "stable", "purpose": "A short status label, tinted by what it means: info, success, warning, danger or neutral.", "description": "Status label. `tone` carries the semantic charge (neutral, info, success, warning, danger); `emphasis` decides how loud the chip reads: `soft` (the default — a tint of the tone, for statuses in rows and headers), `outline`, and `solid` for the one status that must shout. Tone is reinforced by the visible label so colour is never the sole carrier of meaning.", "role": "status", "import": "@rrios-forge/ui/atoms/badge", "exports": [ "Badge", "badgeVariants", "BADGE_EMPHASIS", "BADGE_SIZES", "BADGE_TONES" ], "source": "packages/ui/src/atoms/badge", "axes": [ { "axis": "emphasis", "part": null, "values": [ "soft", "outline", "solid" ], "default": "soft", "meaning": "How strongly a control or chip asserts itself, quiet to loud." }, { "axis": "tone", "part": null, "values": [ "neutral", "info", "success", "warning", "danger" ], "default": "neutral", "meaning": "Which semantic colour family the element speaks in." }, { "axis": "size", "part": null, "values": [ "sm", "md", "lg" ], "default": "md", "meaning": "Ergonomic scale, in three families (control, text, container)." } ], "needs": [ { "need": "Avatar / badge / separator / icon", "answer": "`Avatar` / `Badge` / `Separator` / `Icon`" } ], "patterns": [], "a11yExceptions": [], "decisions": [ { "id": "ADR-002", "title": "Component variants live in `variants.ts` and export their option metadata" } ], "stories": [ { "name": "Playground", "id": "components-atoms-badge--playground", "interaction": false, "snapshots": [ "dark", "light" ], "skipsSnapshot": false, "docs": "/?path=/story/components-atoms-badge--playground", "frame": "/iframe.html?id=components-atoms-badge--playground&viewMode=story" }, { "name": "Tones", "id": "components-atoms-badge--tones", "interaction": false, "snapshots": [ "dark", "high-contrast", "light" ], "skipsSnapshot": false, "docs": "/?path=/story/components-atoms-badge--tones", "frame": "/iframe.html?id=components-atoms-badge--tones&viewMode=story" }, { "name": "Emphases", "id": "components-atoms-badge--emphases", "interaction": false, "snapshots": [ "dark", "light" ], "skipsSnapshot": false, "docs": "/?path=/story/components-atoms-badge--emphases", "frame": "/iframe.html?id=components-atoms-badge--emphases&viewMode=story" }, { "name": "Sizes", "id": "components-atoms-badge--sizes", "interaction": false, "snapshots": [ "dark", "light" ], "skipsSnapshot": false, "docs": "/?path=/story/components-atoms-badge--sizes", "frame": "/iframe.html?id=components-atoms-badge--sizes&viewMode=story" }, { "name": "In context", "id": "components-atoms-badge--in-context", "interaction": false, "snapshots": [ "dark", "light" ], "skipsSnapshot": false, "docs": "/?path=/story/components-atoms-badge--in-context", "frame": "/iframe.html?id=components-atoms-badge--in-context&viewMode=story" } ], "storyFile": "tooling/storybook/stories/components/atoms/badge.stories.tsx" }, { "id": "button", "name": "Button", "level": "atom", "status": "stable", "purpose": "The action a reader takes, from the one primary call to quiet secondary ones.", "description": "**Purpose.** The verb of the system — a control that *commits an action* with a side effect. Buttons are how users do things; they are not how users navigate.\n\n**When to use.**\n- Submit a form, save changes, confirm a dialog, run an operation.\n- Trigger a destructive action (`intent=\"danger\"`) where the consequence is reversible only by a counter-action.\n- Open a modal, panel or other in-product surface that the user is *staying* in (the URL does not change).\n\n**When NOT to use.**\n- The control changes the URL or opens an external page → use `Link`. Buttons break right-click, middle-click, history and crawlability.\n- The control is icon-only → use `IconButton`. It enforces square hit-area, focus ring and a required `aria-label`.\n- The control is part of a segmented set with persistent selection → use `Tabs` or a `RadioGroup` styled as a toolbar.\n\n**Composes with.**\n- `Icon` (decorative leading glyph) reinforces the label without replacing it.\n- `Spinner` is rendered automatically by the Button when `loading` is true; do not place a `Spinner` inside the children.\n- `Field`, `Dialog`, `FormSection` consume Button as the commit affordance; the Button never owns submit logic itself.\n\n**Accessibility.**\n- Renders a real `