# Poesía

> Poesía is the Forge design system (`@rrios-forge/ui` 0.16.1): 26 atoms, 65 molecules and 15 organisms on DTCG tokens, React 19 and Tailwind v4. Material-first: vibrant glass is the system's material. Variants are semantic axes; colour, size, radius and shadow come from tokens only.

Before writing UI with Poesía: look the need up in needs.json, use the component it names, and read that component's sheet. Never build a local copy of a component that exists (R10).

## Start here

- [Manifest](/atlas/manifest.json): the whole system in one JSON — principles, rules, axes, theme layers, gates, decisions, components
- [Need → component](/atlas/needs.json): which component answers which need
- [DESIGN.md](/DESIGN.md): the system in the nine-section DESIGN.md format — every utility with its token and value per theme

## See a component

- `/atlas/components/<id>?story=<story-name>`: the human sheet, its playground opened on that story live, with controls built from its args and the JSX they produce
- `/iframe.html?id=<story-id>&viewMode=story&globals=theme:dark`: the bare story, to screenshot or test (`theme:light` by day)
- [Thumbnails](/atlas/thumbs/index.json): component id → the story its picture shows; the pictures are `/atlas/thumbs/<id>-light.jpg` and `-dark.jpg`

## Rules (non-negotiable)

- R01 Declared intent: Every core entity must declare intent.
- R02 No appearance-only naming: No core entity may be named only by visual appearance.
- R03 Agnostic core: The Core must not contain code or syntax dependent on React, Tailwind, shadcn or any other implementation.
- R04 Tokens for visual values: Every visual value consumed by implementation must go through a token.
- R05 WCAG AA contrast: 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.
- R06 Themes override values, not semantics: A theme/flavor may override values, but must not create new semantics.
- R07 Rule contract: Every rule must declare scope, severity, validation type and exception policy.
- R08 Documented exceptions: Every exception must declare reason, affected rule, scope and review date.
- R09 Decisions cite contracts: Every relevant decision must link to at least one principle or rule.
- R10 Extend before creating: A new entity must not be created if an existing one can be extended without breaking semantics.
- R11 Pattern contract: Every pattern must declare problem, context, intent, applied rules and limits.
- R12 Token contract: Every token must have category, purpose, lifecycle state and source.
- R13 No circular references: References between tokens, themes and semantic roles must not be circular.
- R14 Aesthetics never override safety: Aesthetic rules must never outrank semantic, accessibility or functional rules.
- R15 Experimental entities are bounded: Every experimental entity must declare usage limits and stabilization or removal criteria.

## Product profiles (product.yaml, ADR-036) — a design brief names one

- tool — Productivity tools, editors, back offices, content management: scheme day; density desktop on desktop screens; atmosphere quiet, still on working screens; motion restraint
- data — Dashboards, analytics, monitoring, status pages: scheme night; density desktop; atmosphere still; motion restraint
- money — Banking, payments, fintech, wallets, trading: scheme day; density default; atmosphere quiet, still; motion restraint
- care — Health, mental health, wellbeing, beauty and care services: scheme day; density default; atmosphere quiet, slow drift; motion polish, gentle; nothing pulsing
- commerce — Shops, marketplaces, bookings, luxury goods: scheme day; density default; atmosphere full on browsing screens, quiet at checkout; motion polish
- reading — Editorial, documentation, courses, long-form content, divination and interpretation texts: scheme day, night available; density default, generous measure; atmosphere quiet reading rooms (the reading sheet); motion restraint
- community — Social, creators, messaging, communities, adult content platforms: scheme night; density default; atmosphere full drift on the home, quiet in conversations; motion polish; play for rare moments (a first post, a milestone)
- learning — Learning products, kids, gamified progress: scheme day; density default; atmosphere full; motion play for rewards and progress, restraint in exercises
- studio — Creative studios, media generation and editing, portfolios: scheme night; density desktop for editing panels; atmosphere still behind the canvas, full on the landing; motion restraint in the editor, polish elsewhere
- developer — Developer tools, APIs, consoles, status of services: scheme night; density desktop; atmosphere still; motion restraint
- landing — Marketing and launch pages: scheme the product's; density default; atmosphere full, drifting; motion polish, one signature moment

## Data visualization (dataviz.yaml, ADR-036)

- Compare magnitude, low to high → bar or column; heatmap for a grid (sequential, or one series colour)
- Trend over time → line; area for a single series (one series colour, or categorical for a few series)
- Tell distinct series apart → grouped or stacked bar, multi-line (categorical, in slot order)
- One series is the point, the rest are context → emphasis — one series in colour, the rest in the neutral tone (one series colour plus neutral)
- Above or below a baseline; delta to a target → diverging bar, or a line against the baseline (diverging)
- Part to whole → stacked bar (horizontal for many or long names); a donut only for five slices or fewer with a dominant one (categorical)
- Ordered-scale share (agree to disagree, sentiment) → diverging stacked bar, centred on the neutral (diverging)
- Before and after per item → dumbbell (one series colour in two steps)
- Distribution or spread → histogram, box plot; scatter for two continuous variables (twenty points or more) (one series colour; at most three categorical series in a scatter)
- Intensity over two dimensions (hour by day) → heatmap with a numeric legend (sequential)
- Never: Two y-axes on one chart. Two measures of different scale are two charts, small multiples, or indexed to a common base.
- Never: A rainbow scale, or a hue at a diverging midpoint.
- Never: Colour assigned by rank, or repainted when a filter changes the series.
- Never: 3D, gradients, shadows or glows on data marks.
- Never: Pie or donut with more than five slices or near-equal slices.
- Never: A chart for a single number.

## Motion grammar (motion.yaml, ADR-035)

- G1 How often is it triggered? Rare (onboarding, a first success, about monthly) may be expressive: slow duration, emphasized easing. Occasional (daily) is quiet and quick: fast or default. Frequent (typing, list navigation, sorting, filtering, many times per session) does not animate: the change is instant.
- G2 Was it started from the keyboard? 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.
- G3 What is it for? Feedback (a press, a state flip), orientation (where something came from or went), or continuity (content arriving, leaving, resizing). Anything else is decoration and goes. Delight is allowed only for rare moments.
- G4 Does it survive the tenth repetition? If it would annoy on the tenth time, make it faster, smaller, or remove it.
- G5 What is lost without it? 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.
- MR1 Animate transform, opacity, filter and clip-path. Never width, height, margin, padding, top or left (they reflow every frame).
- MR2 Never start from scale 0. Overlays start at 0.95 to 0.96; nothing starts below 0.9.
- MR3 Never ease-in for interface motion, and never the browser's default easing; use the standard or emphasized easing tokens.
- MR4 Overlays grow from their trigger (transform origin at the trigger's side), not from their centre.
- MR5 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.
- MR6 One easing family per register; durations come from the tokens only. A new duration is a token proposal, not a literal.
- MR7 Interruptible motion uses transitions, so a reversal mid-flight retargets. Exit keyframes exist only where a primitive needs them to delay unmounting (ADR-018).
- MR8 No bounce or overshoot on utility controls (menus, toggles, dialogs, settings, errors).
- MR9 will-change only on what is about to move, never globally; keep continuously animated layers few.

## Taste — what generated-by-default looks like (taste.yaml)

- T01 No dominant element (review): 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.
- T02 More than one primary action per region (review): One `intent="primary" emphasis="solid"` per region; the others go to secondary, outline or ghost, or into an ActionGroup.
- T03 Too many type sizes, too close together (capture): 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.
- T04 Template section sequence (review): One claim and its proof per section; delete sections without a claim; order them by the argument.
- T05 Rows of identical icon-topped cards (review): 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.
- T06 Everything centred (capture): Two or three shared left edges for the page; centre at most one moment per screen; never centre a paragraph longer than three lines.
- T07 Too many left edges (review): Align to the container and its grid; reuse two or three anchor lines on purpose.
- T08 Boxes inside boxes (review): 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).
- T09 Thin or empty screens (capture): Make the main element larger or remove the section; give empty states a real action (T37).
- T10 The phone as a shrunken desktop (capture): 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.
- T11 Viewport units that hide content (lint): Use dynamic viewport units (`dvh`) and reserve space for every fixed bar (safe-area utilities).
- T12 Headlines longer than two lines (capture): Cut words before shrinking the size; keep statements as paragraphs; balanced wrapping, no orphan word.
- T13 Eyebrows by default (review): Use the eyebrow role only when it carries information the heading does not (place, category, step); at most one per region.
- T14 Scattered tiny capitals (capture): Sentence case at a readable role, next to what it describes; capitals only for the eyebrow role and short runs.
- T15 Decorative numbering and meta (review): Number only real sequences (Stepper, ordered lists); delete furniture text.
- T16 One word styled differently in a headline (review): One face, one colour per heading. The serif voice is the display role, used once per page.
- T17 Grey body text (review): Body in `content-default`; `muted` only for secondary notes and metadata; quieter means a lower role or tone, never opacity.
- T18 Text too small to read (capture): Body role for reading; caption and eyebrow only for short meta (the eyebrow's 11 px is the floor).
- T19 Justified or ragged-badly text (lint): Left-aligned text, balanced headline wrapping, `max-w-prose` for long text.
- T20 Accent everywhere (review): The accent is for the primary action and focus; at most one other recurring element. Headings stay in ink.
- T21 Decorative gradients (lint): Flat role colours. In Poesía the only gradient is the atmosphere ground, painted by the Atmosphere organism.
- T22 Material without purpose (review): 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.
- T23 Shadows on everything (review): Elevation by role — resting surfaces raised at most; shadows for what floats (popovers, dialogs, toasts) through the elevation tokens.
- T24 Softening with opacity (review): Use the `muted` or `subtle` content tones; opacity only for disabled (`opacity-disabled`).
- T25 Decorative live signals (lint): Loops only for real progress or live data (Spinner, Skeleton, Progress); a static status Badge otherwise.
- T26 Placeholders and fake interfaces (review): A real picture of the subject, a true-size fragment of the real interface with believable data, or type alone.
- T27 Emoji as icons (lint): An SVG through `Icon` (decorative, or with an accessible name); emoji only inside user content.
- T28 Mixed icon styles (review): One family and stroke per hierarchy level, sized by the icon size axis.
- T29 Clip-art decoration (review): The Atmosphere is Poesía's ground; anything else drawn must be the subject's own thing, large, in one language.
- T30 Genre words (lint): Specific nouns and real numbers; test each sentence by asking whether a competitor could sign it.
- T31 Formula sentences (lint): The plainest true sentence — what it is, what it does, for whom.
- T32 Generic action labels (lint): Verb plus object in one to three words ("Save changes", "Book a table"); one label per intent across the product.
- T33 Placeholder data (lint): Realistic, varied names, lengths and numbers — including the longest real value.
- T34 Invented proof (review): True facts only (price, place, inclusions); clearly marked samples to replace when the real proof is missing.
- T35 Hyped or cute tone in system messages (review): Plain, active, sentence case; errors say what happened and how to fix it.
- T36 The wrong waiting state (review): Skeleton in the shape of the content for waits over about a second; reserve the space; Spinner only inside controls.
- T37 Empty states with nothing to do (review): EmptyState with what will appear here and one action to create the first item.
- T38 Dead or hidden interactions (lint): Real destinations; every hover affordance has a tap and keyboard equivalent; the shared focus ring; NavItem `active`.
- T39 Uniform motion everywhere (lint): 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.

## Theme layers (ADR-032)

- dark (mode): data-color-scheme="dark"
- desktop-density (density): data-density="desktop"
- full-transparency-dark (accessibility): data-color-scheme="dark" data-transparency="full"
- full-transparency (accessibility): data-transparency="full"
- high-contrast-dark (accessibility): data-color-scheme="dark" data-contrast="more"
- high-contrast (accessibility): data-contrast="more"
- less-transparency-dark (accessibility): data-color-scheme="dark" data-transparency="less"
- less-transparency (accessibility): data-transparency="less"
- light (base): data-color-scheme="light"
- reduced-motion (accessibility): data-motion="reduce"
- reduced-transparency-dark (accessibility): data-color-scheme="dark" data-transparency="reduce"
- reduced-transparency (accessibility): data-transparency="reduce"

## Atoms

- [Avatar](/atlas/components/avatar.md): A person or entity at a glance — a photo, or initials when there is none.
- [Badge](/atlas/components/badge.md): A short status label, tinted by what it means: info, success, warning, danger or neutral.
- [Button](/atlas/components/button.md): The action a reader takes, from the one primary call to quiet secondary ones.
- [Checkbox](/atlas/components/checkbox.md): An on/off choice, with a mixed state for "select all".
- [Code](/atlas/components/code.md): A name from code inside a sentence: a token, a prop, an API.
- [Container](/atlas/components/container.md): Keeps a page to a readable width, from prose to fluid.
- [Description](/atlas/components/description.md): Quiet supporting text that explains a field or a section.
- [Grid](/atlas/components/grid.md): Lays content out in responsive columns with system gaps.
- [Heading](/atlas/components/heading.md): The title ramp, from section headings to the display serif.
- [Icon](/atlas/components/icon.md): A small symbol sized to sit beside text, in the colour of its words.
- [IconButton](/atlas/components/icon-button.md): An action shown as a single symbol, with a name for screen readers.
- [Input](/atlas/components/input.md): A single line where people type text, with a clear invalid state.
- [Kbd](/atlas/components/kbd.md): A keyboard shortcut, set as keys — like the ⌘K that opens search.
- [Label](/atlas/components/label.md): Names a form control and marks it as required.
- [Link](/atlas/components/link.md): Takes the reader to another page, within a sentence or on its own.
- [Progress](/atlas/components/progress.md): How far a task has got, as a bar.
- [Radio](/atlas/components/radio.md): One choice out of a few, shown together in a group.
- [Separator](/atlas/components/separator.md): A quiet line that divides content, across or along.
- [Skeleton](/atlas/components/skeleton.md): Loading shimmer placeholder.
- [Sparkline](/atlas/components/sparkline.md): A trend in one line, with the current value marked.
- [Spinner](/atlas/components/spinner.md): Indeterminate progress glyph.
- [Switch](/atlas/components/switch.md): Turns a setting on or off, applied at once.
- [Text](/atlas/components/text.md): Body text in the system's sizes and tones.
- [Textarea](/atlas/components/textarea.md): Multi-line text input.
- [VisuallyHidden](/atlas/components/visually-hidden.md): Screen-reader-only content.
- [Wordmark](/atlas/components/wordmark.md): The Poesía brand mark, set as a word.

## Molecules

- [ActionGroup](/atlas/components/action-group.md): Cluster of related actions (e.g. dialog footer).
- [ActivityItem](/atlas/components/activity-item.md): One event in a feed: who did what to what, and when.
- [Alert](/atlas/components/alert.md): A message about the page or a section of it, in the tone of what it says.
- [AvatarGroup](/atlas/components/avatar-group.md): A few people at a glance, overlapping, with a count for the rest.
- [BottomDock](/atlas/components/bottom-dock.md): A raft of page actions pinned to the bottom of the frame.
- [BarList](/atlas/components/bar-list.md): Names ranked by a value — a label, the value and a thin bar per row.
- [Breadcrumb](/atlas/components/breadcrumb.md): Where the reader is: the trail of pages above this one, each a link back.
- [Card](/atlas/components/card.md): A content surface that groups one subject, with optional actions.
- [Carousel](/atlas/components/carousel.md): A row of slides to swipe or step through.
- [ChatBubble](/atlas/components/chat-bubble.md): One message in a conversation, sent or received. (experimental)
- [ChoiceGroup](/atlas/components/choice-group.md): Pick one or many from a short set, each choice with a title and a line of detail.
- [Combobox](/atlas/components/combobox.md): A select you can type into to filter a long list.
- [CommandItem](/atlas/components/command-item.md): One command in the command menu, with its icon and shortcut.
- [CommentItem](/atlas/components/comment-item.md): One comment: who wrote it, what they said, and the reactions to it. (experimental)
- [ConfirmDialogContent](/atlas/components/confirm-dialog-content.md): Asks a reader to confirm or cancel before something that matters.
- [DataRow](/atlas/components/data-row.md): Generic row for narrow lists (settings, audit).
- [DateField](/atlas/components/date-field.md): Date input with custom calendar popover.
- [Dialog](/atlas/components/dialog.md): A modal surface for a focused task; the page waits behind it.
- [Drawer](/atlas/components/drawer.md): A panel that slides in from an edge for a secondary task.
- [DropdownMenu](/atlas/components/dropdown-menu.md): A menu of actions opened from a button.
- [EmptyState](/atlas/components/empty-state.md): Tells people why a surface is empty and what to do first.
- [ErrorSummary](/atlas/components/error-summary.md): Lists what went wrong in a form and takes people to each mistake.
- [Field](/atlas/components/field.md): One form question: its label, the control, a hint and any error.
- [FileDropzone](/atlas/components/file-dropzone.md): Lets people drop files onto an area or browse for them.
- [FilterBar](/atlas/components/filter-bar.md): Narrows a list by a few filters and shows which ones are on. (experimental)
- [FormSection](/atlas/components/form-section.md): Gathers related form fields under a title and a short explanation.
- [InputGroup](/atlas/components/input-group.md): A text input joined with a prefix, a suffix or a button.
- [InputOtp](/atlas/components/input-otp.md): Takes a one-time code, one digit per box, pasted or typed.
- [ListItem](/atlas/components/list-item.md): One row of a list: a title, a line of detail and an action.
- [LoadingState](/atlas/components/loading-state.md): What a surface shows while it loads: a spinner, a skeleton of its content, or progress.
- [LocaleSelector](/atlas/components/locale-selector.md): Locale picker with native language names.
- [Markdown](/atlas/components/markdown.md): Model or editorial Markdown painted with atoms; app pieces through render slots. (experimental)
- [MetricCard](/atlas/components/metric-card.md): One number that matters, with its label, unit and change.
- [NavGroup](/atlas/components/nav-group.md): Gathers related navigation rows into one group, with or without a title.
- [NavItem](/atlas/components/nav-item.md): A navigation row — an icon in the rail that opens its peek, a labelled row in a panel.
- [NotificationItem](/atlas/components/notification-item.md): One notification: who, what happened and when.
- [PageHeader](/atlas/components/page-header.md): The top of a page: its title, a line about it and its main actions.
- [Pagination](/atlas/components/pagination.md): Moves through a long list a page at a time.
- [PlanCard](/atlas/components/plan-card.md): One pricing plan: its name, price, what it includes and how to choose it.
- [Popover](/atlas/components/popover.md): A small floating surface anchored to what opened it.
- [PricingOption](/atlas/components/pricing-option.md): One choice of plan, to pick among a few.
- [PropertyList](/atlas/components/property-list.md): Key/value rows for record metadata.
- [ReactionBar](/atlas/components/reaction-bar.md): Quick emoji reactions with their counts; the reader's own stands out. (experimental)
- [ScrollArea](/atlas/components/scroll-area.md): Scrolls one axis with soft edge fades instead of a heavy scrollbar.
- [SearchField](/atlas/components/search-field.md): A search box that can be cleared in one press.
- [SegmentedControl](/atlas/components/segmented-control.md): One of a few values, all in view; the thumb slides to the choice.
- [SectionHeader](/atlas/components/section-header.md): Sub-section title within a page body.
- [Select](/atlas/components/select.md): Picks one value from a list in a dropdown.
- [SettingsField](/atlas/components/settings-field.md): One setting: what it does, in a line, and its control.
- [Sheet](/atlas/components/sheet.md): A document pane: one surface divided into sections.
- [SidebarSection](/atlas/components/sidebar-section.md): The sidebar's content — in the rail, one group of rows.
- [Slider](/atlas/components/slider.md): Picks a value along a range by dragging.
- [SplitAction](/atlas/components/split-action.md): A main action with a menu of related ones beside it.
- [StatusRow](/atlas/components/status-row.md): The state of one thing, named and explained in a line.
- [Stepper](/atlas/components/stepper.md): Multi-step process indicator.
- [TableHeader](/atlas/components/table-header.md): DataTable header cells with sort indicators.
- [TablePagination](/atlas/components/table-pagination.md): Pagination footer for DataTable.
- [TableRow](/atlas/components/table-row.md): One row of a table, selectable when the table is.
- [Tabs](/atlas/components/tabs.md): Switches between sibling views of the same subject.
- [TimelineItem](/atlas/components/timeline-item.md): One step in a timeline: what happened, who did it and when.
- [Toast](/atlas/components/toast.md): A brief message about something that just happened.
- [Toolbar](/atlas/components/toolbar.md): Generic horizontal toolbar of actions.
- [Tooltip](/atlas/components/tooltip.md): A short label that appears on hover or focus.
- [TopBar](/atlas/components/top-bar.md): Brand, search and actions across the top of a page without a rail.
- [UserMenuContent](/atlas/components/user-menu-content.md): The account menu: who is signed in, their settings, and sign out.

## Organisms

- [Atmosphere](/atlas/components/atmosphere.md): The sky behind the glass — a themed ground with slow-drifting light.
- [AuthCard](/atlas/components/auth-card.md): Sign in and sign up: credentials, a one-time code, a forgotten password, and what follows each.
- [Composer](/atlas/components/composer.md): Writes a message or post — text, attachments, mentions and send. (experimental)
- [Chart](/atlas/components/chart.md): Line, area and column charts with a legend, a table view and keyboard readout.
- [CommandMenu](/atlas/components/command-menu.md): Finds and runs anything from the keyboard (⌘K).
- [CommentsThread](/atlas/components/comments-thread.md): A discussion: comments, replies to them and a box to add yours. (experimental)
- [DataTable](/atlas/components/data-table.md): Shows records in rows and columns that people can sort, select and page through.
- [Feed](/atlas/components/feed.md): A stream of posts that loads more as people scroll.
- [FeedCard](/atlas/components/feed-card.md): One post in a feed: who wrote it, what it says and how people reacted.
- [Form](/atlas/components/form.md): Runs a whole form: checks every answer and shows what needs fixing before it sends.
- [Hero](/atlas/components/hero.md): The opening section of a landing or welcome page, with its headline and main action.
- [MediaLightbox](/atlas/components/media-lightbox.md): Shows a picture or video full screen, to zoom and step through. (experimental)
- [NotificationCenter](/atlas/components/notification-center.md): Dropdown-anchored notification panel.
- [PageShell](/atlas/components/page-shell.md): The app frame: an icon rail whose rows peek, the page header, the content; tabs on phones.
- [ProfileHeader](/atlas/components/profile-header.md): The top of a profile — cover, avatar, name, stats and actions. (experimental)

## Optional

- [ADR-001 — Token sources are JSON, not TypeScript](https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-001-token-sources-are-json.md)
- [ADR-002 — Component variants live in `variants.ts` and export their option metadata](https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-002-component-variants-in-variants-ts.md)
- [ADR-003 — Storybook editorial convention and pattern↔component bidirectionality](https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-003-storybook-editorial-convention.md)
- [ADR-004 — Migrate boolean configuration props to semantic axes](https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-004-boolean-props-to-semantic-axes.md)
- [ADR-005 — Visual operational rules: surfaces, interaction, motion](https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-005-visual-operational-rules.md)
- [ADR-006 — Geometry and typography signature](https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-006-geometry-and-typography-signature.md)
- [ADR-007 — Material highlight on raised surfaces](https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-007-material-highlight-on-raised-surfaces.md)
- [ADR-008 — Layout layer: refined `Grid` + new `Container`](https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-008-layout-layer-grid-and-container.md)
- [ADR-009 — Editorial Frame: PageShell v3 + new `TopBar` molecule](https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-009-editorial-frame-page-shell.md)
- [ADR-010 — PageShell v4: bottom dock + mobile floating bubble](https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-010-page-shell-bottom-dock.md)
- [ADR-011 — PageShell v5: adaptive lateral sidebar + mobile nav bubble](https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-011-pageshell-v5-mobile-nav-bubble.md)
- [ADR-012 — Card.fill axis for symmetric growth in grids](https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-012-card-fill-axis.md)
- [ADR-013 — PageShell: mobile-nav polymorphism](https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-013-pageshell-mobile-nav-polymorphism.md)
- [ADR-014 — PageShell: Apple Mail / macOS Big Sur visual register](https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-014-pageshell-apple-mail-register.md)
- [ADR-015 — Drawer molecule on top of Radix Dialog](https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-015-drawer-molecule.md)
- [ADR-016 — NotificationCenter v2: Popover → Drawer + Provider/Hooks](https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-016-notification-center-drawer-provider.md)
- [ADR-017 — Actionable components adopt the `asChild` slot pattern for framework-aware routing](https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-017-actionable-as-child-pattern.md)
- [ADR-018 — Motion language as a Pattern Layer contract](https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-018-motion-language-pattern.md)
- [ADR-019 — Composer organism (message/post authoring surface)](https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-019-composer-organism.md)
- [ADR-020 — Feed `anchor="bottom"` (conversation mode) instead of a ChatThread organism](https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-020-feed-anchor-bottom.md)
- [ADR-021 — ProfileHeader organism and the `cover` slot contract](https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-021-profile-header-organism.md)
- [ADR-022 — The material family: `solid` and `vibrant`](https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-022-material-family-vibrant.md)
- [ADR-023 — Atmosphere grammar: colour, motion, and meaning](https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-023-atmosphere-grammar.md)
- [ADR-024 — `LocaleSelector` is a new molecule, not an extension of `Combobox`](https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-024-locale-selector.md)
- [ADR-025 — The sidebar is an island, not a wall (amended: two stagings)](https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-025-sidebar-island.md)
- [ADR-026 — Sunset functional palette + the stage field](https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-026-sunset-functional-palette.md)
- [ADR-027 — Vibrant is the system's material, not one of its members](https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-027-vibrant-is-the-system.md)
- [ADR-028 — The label is not the fill](https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-028-label-is-not-the-fill.md)
- [ADR-029 — The page gutter belongs outside the frame](https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-029-the-page-gutter.md)
- [ADR-030 — Axis vocabulary: one name, one meaning](https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-030-axis-vocabulary.md)
- [ADR-031 — Tokens that cover the system: type roles, focus, ambient motion, control heights](https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-031-token-coverage.md)
- [ADR-032 — Themes compose by layers; brands are a checked layer](https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-032-theme-layers-and-brand.md)
- [ADR-033 — The material ships once, and the night is tokens](https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-033-material-engineering.md)
- [ADR-034 — Accessible names come from a labels provider](https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-034-accessible-names-from-a-labels-provider.md)
- [ADR-035 — Motion grammar: the gate before motion, slop by repetition, and what reduced motion keeps](https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-035-motion-grammar.md)
- [ADR-036 — Data visualization: colour roles, a grammar, and three components on plain SVG](https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-036-data-visualization.md)
- [ADR-037 — Continuity motion: a decelerating curve, a travelling indicator, view transitions and the SegmentedControl](https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-037-continuity-motion.md)
- [ADR-038 — Liquid Glass layers: glass for navigation and controls, a content material for everything read](https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-038-liquid-glass-layers.md)
- [ADR-039 — The component premium pass: translucent fills, a selected register, quiet scroll, and a system-wide audit](https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-039-component-premium-pass.md)
- [ADR-040 — The sidebar collapses by default and gives the page the room](https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-040-collapsible-sidebar.md)
- [ADR-041 — The rail peeks instead of growing](https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-041-rail-peek.md)
- [ADR-042 — The reader chooses the material: a transparency layer](https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-042-transparency-layer.md)
- [ADR-043 — The default theme is monochrome](https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-043-monochrome-default.md)
- [ADR-044 — Navigation is a rail that peeks](https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-044-rail-navigation.md)
- [ADR-045 — A screen's controls pin and condense](https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-045-sticky-bars.md)
- [ADR-046 — Markdown is painted with atoms, and apps fill its slots](https://git.rrios.dev/rrios-forge/forge/src/branch/main/docs/poesia/DECISION_LOGS/ADR-046-markdown-molecule.md)