poetry-ui 0.0.2

data/lib/generators/poetry/skill/templates/poetry-component/references/anatomy.md

@@ -0,0 +1,152 @@
+# Component anatomy - the canonical section order
+
+Every poetry component class reads top to bottom in the same order.
+The order is chosen so a reader meets the component the way an agent
+consumes its contract: identity, vocabulary, surface, behavior,
+arguments, structure, then implementation.
+
+## The order
+
+| # | Section | Declares |
+|---|---------|----------|
+| 1 | Includes & class config | `include` / `extend`, `internal_component!`, `requires_content`, `delegate`, `with_collection_parameter` |
+| 2 | Constants | vocabularies first (`VARIANTS`, `SIZES`, ...), then the agent contract (`AGENT_RULES`, `REQUIRES_ANY`, `SLOT_RENDERS`) |
+| 3 | Slots | `renders_one` / `renders_many` |
+| 4 | Stimulus | `use_stimulus do ... end` |
+| 4b | Agent tools | `tool :name, executes:, ...` (interactive components; optional) |
+| 5 | Styles & options | `style` declarations, then `option` declarations |
+| 6 | Validations | `validates` / `validate` |
+| 7 | Parts | `part` declarations |
+| 8 | Lifecycle | `initialize`, `before_render`, `call` - in that order |
+| 9 | Public methods | everything else callable from templates or callers |
+| 10 | Private methods | under a single `private` |
+| 11 | Nested classes | builder / internal classes, last |
+
+## Why this order
+
+- **Constants come before the DSL calls that read them.** Ruby
+  evaluates the class body top to bottom; `style :variant, variants:
+  VARIANTS` needs `VARIANTS` already defined. Putting every constant in
+  one early section satisfies this everywhere at once.
+- **The agent contract lives with the constants.** `AGENT_RULES`,
+  `REQUIRES_ANY`, and `SLOT_RENDERS` are data the machine surfaces
+  project; grouping them right after the vocabularies keeps the whole
+  published contract readable in one screen.
+- **Slots before behavior, behavior before arguments.** What the
+  component holds (slots), how it acts (Stimulus), what it accepts
+  (styles, options, validations), what it renders (parts). Each section
+  answers the next question a reader has.
+- **Lifecycle heads the public methods.** `initialize` is the first
+  public method anyone looks for; `before_render` and `call` follow it
+  so the render path reads as one block.
+
+## Hard rules
+
+1. **Never reorder declarations within a section.** Option, part, and
+   slot order is projected into the registry and the agent surface in
+   declaration order. Moving a whole section preserves it; shuffling
+   inside a section changes a machine surface.
+2. **One `private` keyword.** Everything below it is private; no
+   interleaving public and private methods.
+3. **Inner classes declare `internal_component!`** when they inherit
+   the component machinery but are not published components in their
+   own right.
+4. **Nested classes sit at the end of the class but above the
+   `private` divider.** A constant is never private-scoped, so placing
+   one below `private` is misleading (and linters flag it). A nested
+   class a class-body DSL call evaluates must stay above that call
+   instead.
+5. **`frozen_string_literal: true`** heads every file.
+
+## Skeleton
+
+```ruby
+# frozen_string_literal: true
+
+module MyApp
+  module Callout
+    # A bordered notice that frames one message and an optional action.
+    # Reaches for the semantic-role tokens, so every theme styles it
+    # without per-instance CSS.
+    #
+    # @example Basic usage
+    #   render MyApp::Callout::Component.new(variant: :info) { "Saved." }
+    class Component < Poetry::Core::Component
+      requires_content "the message body"
+
+      VARIANTS = %i[info success warning danger].freeze
+
+      AGENT_RULES = [
+        "Use Callout for inline notices - never a hand-styled div.",
+        "Pick the variant by intent; danger is reserved for destructive outcomes."
+      ].freeze
+
+      renders_one :action
+
+      use_stimulus do
+        controller :callout do
+          target :dismiss
+        end
+      end
+
+      style :variant, default: :info, required: true, variants: VARIANTS
+
+      option :dismissible, :boolean, default: false
+
+      validates :variant, inclusion: { in: VARIANTS }
+
+      part "root", "The bordered container - variant state rides here",
+           states: { "data-variant" => { condition: "always", values: VARIANTS.map(&:to_s) } }
+      part "action", "Wrapper around the action slot"
+
+      def initialize(...)
+        super
+      end
+
+      def before_render
+        ensure_content!
+      end
+
+      def dismiss_label
+        t(".dismiss")
+      end
+
+      private
+
+      def css
+        # section-level styles resolved by the style DSL
+      end
+    end
+  end
+end
+```
+
+## Agent tools (the operate surface)
+
+Beside `use_stimulus`, an interactive component may declare the tools an
+in-page agent (WebMCP, `document.modelContext`) can invoke on a rendered
+instance. Each tool is MCP `Tool`-shaped and dispatches to one of the
+component's OWN Stimulus actions, positionally in declared parameter order:
+
+```ruby
+tool :set_value,
+     description: "Activate the tab whose value matches and show its panel.",
+     params: { value: { type: "string", required: true, description: "The tab's value." } },
+     executes: :set_value,   # a declared controller action - validated at class load
+     mutating: true          # read-only by default; the annotation says which
+```
+
+Rules: declare `use_stimulus` first; keep `executes:` bare (`:open`) when a
+subclass may re-controller the root (Sheet over Dialog) - it re-resolves per
+class; descriptions are positive, single-purpose, at most 500 characters.
+Override `webmcp_tool_definition(definition)` to refine a schema with what
+only the rendered instance knows (Tabs adds its tab values as the enum).
+Nothing registers until a call opts in: `poetry_tabs(webmcp: "sections")`.
+The registry projects tools to llms-full.txt, `describe_component`, and the
+docs page; `poetry:check` gates the opt-ins (`webmcp-without-tools`,
+`webmcp-name`, `webmcp-duplicate-name`).
+
+A component may not need every section - Button has no `use_stimulus`,
+static components have no validations. Skip absent sections entirely;
+never leave placeholder comments for them. The sections that are
+present appear in this order.

data/lib/generators/poetry/skill/templates/poetry-component/references/checklist.md

@@ -0,0 +1,67 @@
+# Component audit checklist
+
+Run this against one component file at a time, top to bottom - the
+checks are ordered so violations surface in file order. The audit has
+two passes: structure, then documentation. It never changes behavior:
+rendered output, projected surfaces, and test results are identical
+before and after an audit fix, except where a projected string was
+itself the finding.
+
+## Pass 1 - structure
+
+- [ ] `# frozen_string_literal: true` heads the file.
+- [ ] Sections present appear in canonical order: includes & class
+      config → constants → slots → stimulus → styles & options →
+      validations → parts → lifecycle → public methods → private
+      methods → nested classes. (Absent sections are skipped, not
+      stubbed.)
+- [ ] Constants: vocabularies before the agent contract
+      (`AGENT_RULES`, `REQUIRES_ANY`, `SLOT_RENDERS`); every constant
+      above the first DSL call that reads it; all `.freeze`d.
+- [ ] No declaration was reordered *within* its section - option,
+      part, and slot order projects in declaration order. Verify with
+      the diff, not by eye.
+- [ ] Lifecycle methods (`initialize`, `before_render`, `call`) lead
+      the public methods, in that order.
+- [ ] Exactly one `private` keyword; nothing public below it.
+- [ ] Inner machinery classes declare `internal_component!`.
+- [ ] Nested classes sit last in the class body, above the `private`
+      divider (constants are never private-scoped).
+
+## Pass 2 - documentation
+
+- [ ] Class docblock: purpose in 1-3 sentences + at least one
+      `@example` (published components); `@api private` one-liner
+      (internal components).
+- [ ] Public methods with non-obvious signatures carry `@param` /
+      `@return`; examples where usage isn't clear from the signature.
+- [ ] Projected strings (part descriptions, agent rules, option
+      descriptions, `requires_content` hints) read consumer-facing:
+      concrete DOM reality, explicit conditions, imperative rules.
+- [ ] No internal references anywhere in comments: no planning-doc or
+      decision-index citations, no milestone names, no links to
+      private notes. Reasoning is stated inline or removed.
+- [ ] No other library named in any comment or string (notices file
+      excepted).
+- [ ] No narration comments (restating the next line) and no
+      reviewer-addressed comments.
+- [ ] Comment prose is complete sentences; abbreviations only if a
+      newcomer reads them cold.
+
+## Verification
+
+- [ ] Full suite green.
+- [ ] `git diff` shows only: comment changes, section moves, doc
+      strings intentionally rewritten. No logic lines changed.
+- [ ] If a projected string changed: the registry / agent-surface /
+      check tests that assert on it were updated in the same change,
+      and the new text is an improvement for the consumer, not a
+      paraphrase.
+- [ ] `yard doc` (or the gem's docs build) runs warning-clean on the
+      touched files.
+
+## Recording findings that are out of scope
+
+Anything discovered that is *not* structure or documentation - a bug, a
+missing validation, a contract gap - does not get fixed in an audit
+pass. Record it separately and keep the audit diff clean.

data/lib/generators/poetry/skill/templates/poetry-component/references/documentation.md

@@ -0,0 +1,137 @@
+# Documentation standard
+
+poetry components carry two kinds of documentation, and they have
+different readers. YARD comments serve the person or agent reading the
+source; projected strings (part descriptions, agent rules, option
+metadata) are published verbatim through the registry, the agent
+surface, and the docs. Write each for its consumer.
+
+## The class docblock
+
+Every published component class opens with a YARD docblock:
+
+- **One to three sentences** on what it renders and when to reach for
+  it. Present tense, no history. This is the *reference lead* - a public
+  reader with zero codebase context must parse every word.
+- Optionally ONE short paragraph of load-bearing behavior facts a USER
+  needs (keyboard behavior, required slots, form participation), written
+  to stand alone. Maintainer rationale is a different register: it lives
+  as a plain comment above the method it concerns, never in the class
+  docblock. Whole docblock ≤ 15 lines.
+- **One `@example`** showing minimal usage through the helper or
+  `render`. Add a second example only when the primary axis (variant,
+  size, slots) isn't obvious from the first.
+- Internal component classes (`internal_component!`) get a one-line
+  comment and `@api private` instead.
+
+```ruby
+# Renders a dismissible inline notice with an optional action slot.
+# Variants map to semantic intent, so themes restyle it wholesale.
+#
+# @example
+#   render MyApp::Callout::Component.new(variant: :success) { "Saved." }
+class Component < Poetry::Core::Component
+```
+
+## Public methods
+
+- YARD tags (`@param`, `@return`, `@example`) on every public method
+  whose signature or return isn't obvious from the name.
+- Template-facing methods (`*_attributes`, `*_id`, `*_classes`, part
+  builders) and lifecycle overrides (`initialize`, `before_render`,
+  `call`) carry a one-line comment ending in `@api private` - they are
+  public for the template's sake, not the consumer's, and the doc set
+  hides them.
+- Hand-written slot writers a caller uses (`with_*`) are real public
+  API: full docs, never `@api private`.
+- Markdown markup; full sentences; wrap at the file's prevailing width.
+
+## Declaration docs
+
+Every `option` and `style` carries a `doc:` string, and every
+`renders_one`/`renders_many` carries one too - with `renders:` passing
+the slot's lambda as a keyword so the doc reads first. (`slot_doc` is
+the fallback for a doc declared away from its declaration, e.g. in a
+different module.) That string is the declared surface's documentation everywhere at
+once - the registry (option/style/slot descriptions), llms.txt and the
+agent surface, the component page's API section, and the generated API
+reference - with the machine facts (type, default, variants)
+auto-appended, so the prose adds MEANING only:
+
+- One sentence, two at most: the caller-visible effect and its
+  interactions ("Ignored unless `tag: :a`."), never the implementation
+  ("sets @foo").
+- Never repeat the type, default, or variant list - the projections
+  carry those already.
+
+```ruby
+option :loading, :boolean, default: false,
+       doc: "The no-JS loading state: aria-busy, a spinner, and the control disabled."
+
+renders_one :leading, doc: "Optional leading visual, rendered inside the icon span."
+
+renders_one :trigger,
+            doc: "The button that opens the dialog.",
+            renders: lambda { |**options, &block| ... }
+```
+
+Constants that define the surface get one-liners too: vocabulary arrays
+("The closed vocabulary for the variant axis."), `AGENT_RULES`
+("Projected into the registry, llms.txt, and the agent surface.").
+
+## Private methods
+
+Plain comments, and only where the *why* isn't visible in the code. A
+private method whose name states its job needs no comment.
+
+## Projected strings
+
+Part descriptions, agent rules, option and slot descriptions, and
+`requires_content` hints are machine-published documentation:
+
+- Write for the consumer who has never seen the source: name the DOM
+  reality ("the rendered control itself"), the condition ("loading: is
+  set"), the rule ("icon-only buttons MUST pass label:").
+- No abbreviations that only make sense inside this codebase.
+- Agent rules are imperatives: what to do, what never to do, one rule
+  per entry.
+
+## What comments never contain
+
+Comments explain the component to its next reader. Reasoning stands on
+its own - state the constraint, not where it came from:
+
+- **No internal references**: planning documents, decision indexes,
+  milestone names, issue numbers, links into private notes. If the
+  reasoning matters, write the reasoning; the citation is noise to
+  every reader who isn't the author.
+- **No other libraries**: naming another library belongs in
+  `THIRD_PARTY_NOTICES.md` when code was adapted, and nowhere
+  otherwise. "The base-contract rule: an icon-only control without an
+  accessible name never ships" carries the rule; attribution lives in
+  the notices file.
+- **No narration**: nothing that restates what the next line does, and
+  nothing addressed to a reviewer ("this is correct because..."). A
+  comment earns its place by stating a constraint the code can't show.
+
+## YARD setup
+
+Each gem carries a `.yardopts` (markdown markup, README as the index,
+`--hide-api private`, previews and generator templates excluded,
+CHANGELOG and notices as extra files) and loads the shared handler kit
+(`poetry-core/yard/poetry_yard.rb`), which makes the declarative
+surfaces - `class_methods do`, `option`/`style` readers, slot writers,
+`part` anatomy - visible to the doc build.
+
+Gates, from the gem root:
+
+- `rake yard:verify` - fails on any warning (an unresolvable reference
+  or malformed tag is a review finding; structural warnings are
+  allowlisted in the task).
+- `rake yard:coverage` - the ratchet: fails when the undocumented-object
+  count exceeds the committed `.yard_coverage` floor. After a
+  documentation pass, lower the floor with `rake yard:coverage:record`.
+
+Previews are OUTSIDE the doc set: preview.rb comments are for gallery
+authors (Lookbook tags like `@label`/`@!group` live there) and are never
+published.

data/lib/generators/poetry/skill/templates/poetry-design/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: poetry-design
+description: >-
+  Design guidance for building poetry UIs: theme selection, page
+  composition (macrostructure, hierarchy, containment, status color),
+  the visual audit of a finished screen, and studying a brand into a
+  DESIGN.md. Load this WHENEVER building, composing, or restyling a
+  page, screen, dashboard, or view with poetry - alongside the poetry
+  usage skill, before composing - not only when the task mentions
+  design.
+---
+
+# poetry-design - the taste layer
+
+poetry's catalog guarantees valid, accessible components; this skill covers
+the decisions the catalog cannot make for you: which theme, what
+macrostructure, whether the finished page reads well. Any task that builds
+a PAGE is a design task - load this before composing, not after something
+looks wrong. It works through tokens, variants, themes, and DESIGN.md -
+**never per-instance CSS** (that reintroduces the drift the system exists
+to prevent).
+
+## Verbs
+
+- **theme** (`references/theme.md`) - pick or adapt one of the nine shipped
+  themes; wire a brand in through the DESIGN.md import door.
+- **compose** (`references/compose.md`) - shape a page BEFORE building it:
+  macrostructure, hierarchy, framing, content realism. The checklist here
+  is distilled from judged head-to-head runs.
+- **audit** (`references/audit.md`) - review a finished screen: run the
+  deterministic design-lint tier first, then the critique checklist for
+  what detectors cannot see.
+- **study** (`references/study.md`) - extract a brand's design DNA into a
+  DESIGN.md poetry can import; `redesign` = keep the content, swap the
+  fingerprint.
+- **figma** (`references/figma.md`) - bring a Figma design into poetry:
+  import its variables as an AA-gated theme, or translate a selection into
+  components across the Figma + poetry MCPs.
+- **paper** (`references/paper.md`) - bring a paper.design canvas into
+  poetry: import its theme, or translate the canvas across the Paper +
+  poetry MCPs.
+
+## Working rules
+
+- Deterministic first: run the linters before offering opinions - most slop
+  is mechanically detectable, and every rule names its fix.
+- Express every fix through a token, variant, option, theme, or DESIGN.md
+  override. If a fix seems to need hand-written CSS, the real fix is a
+  different composition (or an upstream gap worth reporting). The one
+  sanctioned exception: a DECLARED `cn-*` override - host CSS restyling a
+  theme-owned class, recorded with a reason under `overrides:` in
+  config/poetry_components.yml after the user confirms intent
+  (`bin/rails poetry:design:overrides` reports drift). Never declare an
+  override to skip a fix.
+- For component contracts (options, slots, variants), load the `poetry`
+  usage skill; this skill assumes you compose through it.

data/lib/generators/poetry/skill/templates/poetry-design/references/audit.md

@@ -0,0 +1,123 @@
+# audit - review a finished screen
+
+Deterministic first, judgment second. Most AI-UI slop is mechanically
+detectable; run the machines before offering opinions. And the machines
+also run LAST: any edit the audit produces re-opens the gate - finish
+with a clean `poetry:check` run AFTER the final edit, never before it.
+
+## Run the linters
+
+- `bin/rails poetry:check` - the hard gate: unknown components, options,
+  variants, icon names, arity, wiring. Errors block; fix them first.
+- `POETRY_CHECK_DESIGN=1 bin/rails poetry:check` - adds the design-slop
+  tier (warnings; the taste tier). `POETRY_CHECK_JSON=1` for machine
+  output; both accept a glob argument for one file.
+- `bin/rails poetry:verify` - classes vs the compiled CSS (catches classes
+  that never compiled, i.e. styles silently not applying).
+
+## The design-lint rules (what each catches)
+
+Every finding names its fix in the message. The 23 rules:
+
+- `card-in-card` - a Card nested in a Card; flatten to one containment level.
+- `icon-tile-over-heading` - the decorative icon-in-a-tile stacked above
+  every heading; the stock AI-UI tell.
+- `wall-of-cards` - everything boxed identically; vary the surface or merge
+  regions.
+- `off-scale-arbitrary` - `w-[347px]`-style values that sit off the scale;
+  use the scale spelling.
+- `gradient-off-token` - gradients built from palette utilities instead of
+  tokens.
+- `heading-skip` - h1 -> h3 ladder skips (remember Card titles default h3;
+  pass `title_tag:`).
+- `mixed-status-weight` - solid and soft status pills mixed in one table;
+  keep one treatment family per surface.
+- `center-everything` - body copy and controls center-aligned page-wide;
+  center is for empty states and heroes.
+- `shadow-stack` - stacked/oversized shadows on nested surfaces.
+- `type-scale-monotony` - all content text at one size; hierarchy needs a
+  scale (DOM tier - reads computed styles).
+- `adjacent-same-surface` - sibling regions with identical surfaces and no
+  separation (DOM tier).
+- `contrast-adjacent` - adjacent text failing contrast against its own
+  surface (DOM tier).
+- `stock-theme-nudge` - the app still wears the stock look while a foreign
+  DESIGN.md is present (DOM tier).
+- `em-dash-overuse` - five or more em dashes in the page copy; the LLM
+  prose tell. Rewrite most as periods, commas, or parentheses.
+- `marketing-buzzword` - stock SaaS phrases ("streamline your",
+  "enterprise-grade"); say what the product concretely does.
+- `aphoristic-cadence` - "Not a X. Y." / "No X. Just Y." constructions;
+  one lands, three read as generated copy.
+- `numbered-section-markers` - sequential 01/02/03 editorial markers; cut
+  the numbers or vary the section anatomy.
+- `repeated-section-kickers` - a tracked-caps kicker above every section
+  heading; keep at most one.
+- `hero-eyebrow-chip` - a text eyebrow directly above the h1; fold it into
+  the heading or cut it (badge announcement pills are fine).
+- `oversized-h1` - display-size type (text-7xl+) carrying 40+ characters;
+  shorten the headline or step the size down.
+
+Motion floor (perception physics, theme-independent - they read the motion
+utilities an element carries):
+
+- `motion-ease-in` - a bare `ease-in` on a transition; ease-in decelerates
+  into rest, wrong for UI. Use `ease-out` for enters, `ease-in-out` for
+  moves (a state-scoped `data-closed:ease-in` exit is fine).
+- `motion-duration-ceiling` - a UI transition over ~500ms (`duration-700`,
+  `duration-1000`, `duration-[800ms]`); past ~300ms UI reads as laggy.
+- `motion-scale-from-zero` - an animated element resting at `scale-0`; it
+  erupts from nothing. Start from `scale-95` with opacity, not zero.
+
+`transition-all` is a REPORT-ONLY advisory (`bin/rake design:motion`), not a
+gate: it animates every property including layout, so prefer the specific
+transition (`transition-colors`, `transition-[color,box-shadow]`,
+`transition-transform`). poetry ships the upstream default, so re-timing it
+is a design decision, surfaced rather than enforced.
+
+## Score it (deterministic)
+
+When the audit needs a NUMBER - a PR gate, a before/after, a fleet
+sweep - compute the adherence score from findings, never from a
+subjective sense of overall quality (the spectrum-audit rule).
+
+Severity weights, fixed:
+
+- **Critical 10** - each `poetry:check` ERROR (unknown component/option/
+  variant/icon, arity, wiring, slot misuse). These also block outright.
+- **High 5** - each `poetry:verify` failure (a class that never
+  compiled: styling silently not applying).
+- **Medium 2** - each design-slop WARNING (`POETRY_CHECK_DESIGN=1`, the
+  twenty rules above).
+- **Low 1** - each critique-checklist finding (the judgment items; name
+  the surface for every one you count).
+
+Per category: `score = 100 - min(100, sum_of_weights)`. Overall
+adherence = the weighted mean: contracts 40%, compiled styling 25%,
+design slop 25%, critique 10%. Report all four category scores plus the
+overall, each with its finding count - a score with no finding list is
+not a score.
+
+## The critique checklist (what detectors cannot see)
+
+Work the rendered page, not the source:
+
+1. **Squint test** - blur your eyes (or shrink the screenshot): does the
+   page still have a shape - regions, a focal point, a reading order? If
+   it goes uniform gray, hierarchy is missing.
+2. **One-decision test** - can you say in one sentence what this page most
+   wants the user to do? Is that the one filled-primary element?
+3. **Consistency sweep** - same state, same treatment; same gap rhythm per
+   region; aligned edges (one container width, not three).
+4. **Content honesty** - would a real user's data look like this? Plausible
+   distributions, realistic names/dates/amounts, an empty state where the
+   data could be empty.
+5. **Framing** - does the page's subject have breathing room? Does anything
+   sit naked at the viewport origin?
+
+Report findings in the linters' voice: name the surface, name the fix, and
+express every fix through a token, variant, option, theme, or DESIGN.md
+override - never per-instance CSS. Host CSS already touching `cn-*` classes
+is either a DECLARED override (listed by `bin/rails poetry:design:overrides`;
+respect it - it is recorded design intent) or drift to flag, never silently
+extend.

data/lib/generators/poetry/skill/templates/poetry-design/references/compose.md

@@ -0,0 +1,73 @@
+# compose - shape the page before building it
+
+Write the shape down first (a sentence per region), then build. Screens
+composed region-by-region from a stated shape consistently beat screens
+grown element-by-element. The five mechanics below are distilled from
+judged head-to-head runs - they are where composed pages win.
+
+## Step 1 is a tool call, not a decision
+
+Route the brief through the poetry MCP `compose` tool FIRST (no MCP:
+`bin/rails g poetry:block --list` + the `poetry` skill's
+`references/blocks.md`). If it returns a block, START FROM THAT SOURCE and
+edit in place - do not re-derive the layout from the checklist below.
+Blocks arrive with the five mechanics already composed; a blank file
+arrives with none of them, and reading this checklist does not transfer
+them (measured: screens built from scratch after reading it composed no
+better than screens built without it).
+
+For a whole SCREEN, prefer the `build_page` tool over `compose`: it runs
+the guided workflow (probe -> plan -> direct -> snippets -> verify), so the
+page architecture (section order, the states a real screen handles, the
+edge cases), the theme-derived direction, and the source all arrive in
+order, and it finishes on the executable `check` gate. `compose` is the
+single-step router build_page calls at its snippets step; reach for it
+directly for a quick route or a lone component.
+
+## The five mechanics
+
+1. **Containment.** Give each functional region a boundary the eye can
+   find: a Card, a bordered `section`, a `bg-muted/50` band. A page of
+   floating fragments reads unfinished; a page of nested-cards-in-cards
+   reads like slop (the lint catches that direction). One level of
+   containment, used consistently.
+2. **Status color-coding.** Encode state with the status vocabulary
+   (Badge `success` / `warning` / `info` / `destructive`), consistently:
+   the same state always gets the same variant, and one treatment family
+   per surface - solid and soft pills never mix in one table.
+3. **Contextual framing.** A section that IS the page's subject keeps its
+   container and breathing room (`mx-auto max-w-* p-6`); a bare component
+   at the viewport origin reads cramped. Drop the wrapper only when
+   composing into an already-padded frame (an app shell's content area).
+4. **Page furniture.** Real screens have a header (title + description +
+   primary action), section headings, and end-of-list affordances
+   (pagination, a "view all" link). A component demo has none of them; a
+   page needs them.
+5. **Content realism.** Realistic data - names, amounts, dates, statuses in
+   plausible distributions (mostly-fulfilled with a few exceptions, not
+   one of each) - is part of the design. Lorem ipsum and ALL-states-once
+   both read as unfinished.
+
+## Hierarchy and density
+
+- One primary action per view; everything else is `outline`, `ghost`, or a
+  link. Two filled primary buttons side-by-side is a hierarchy bug.
+- Secondary copy goes `text-muted-foreground` at `text-sm` - contrast
+  carries hierarchy more cheaply than size.
+- Respect the heading ladder (h1 -> h2 -> h3, no skips) - note Card titles
+  default to h3; pass `title_tag:` when the card sits higher in the page.
+- Space on the built-in scale, consistently: one gap rhythm per region
+  (`space-y-4` / `gap-4` family), padding steps from the same scale.
+- Destructive flows: tinted boundary + plain-language consequences in
+  AA-clean muted copy; the alert carries icon + title only (description
+  copy on the destructive tint fails AA).
+- Rich navigation panels (title + description grids) want
+  `poetry_navigation_menu(viewport: true)` - the morphing-card mode that
+  keeps panel content contained.
+
+## Iterate against the render
+
+Screenshot or render what you built and look at it before calling it done
+- then run the audit pass (`references/audit.md`). The linters read both
+ERB source and rendered HTML; what they can't see, the critique checklist
+covers.

data/lib/generators/poetry/skill/templates/poetry-design/references/figma.md

@@ -0,0 +1,68 @@
+# figma - bring a Figma design into poetry
+
+Two doors, independent. Take the first for a palette/theme handoff; the
+second when a whole frame must become working components. Both translate
+INTO poetry primitives and tokens - never transcribe Figma's absolute
+positions, raw hex, or pixel gaps into markup.
+
+## Door 1: variables -> an AA-gated theme (no paywall, no MCP)
+
+Figma variables become poetry token overrides through the same importer a
+DESIGN.md uses, so imported swatches inherit poetry's contrast law.
+
+1. In Figma, export the variables as JSON with a free plugin - **Tokens
+   Studio** or **Design Tokens** (six7). These use the Plugin API, which
+   reads variables on every plan; the REST Variables API is Enterprise-only,
+   so do not rely on it.
+2. Run `bin/rails poetry:figma:import[variables.json]` (or
+   `poetry:design:import` - it detects `.json`).
+3. **Read the report.** The importer walks DTCG groups and modes, resolves
+   `{aliases}`, flattens `primary/DEFAULT` and `primary/foreground`, converts
+   hex / rgb / DTCG-object / oklch into poetry's OKLCH model, then measures
+   every touched pair against WCAG AA. A swatch that fails AA is **dropped
+   and reported with the nearest passing value** - never shipped. Anything
+   with no poetry role is dropped and listed too; the importer never guesses.
+4. It writes `app/assets/tailwind/poetry/design-overrides.css` and wires the
+   import. Rebuild CSS. `POETRY_DESIGN_FORCE=1` ships failing pairs on
+   purpose (rarely right); `POETRY_DESIGN_JSON=1` prints a machine report.
+
+Names that do not match a poetry role (`color/brand/600`, say) are dropped,
+not invented. Rename in Figma toward poetry's semantic roles (`background`,
+`foreground`, `primary`, `muted-foreground`, `border`, ...) and re-run.
+
+## Door 2: a selection -> components (dual-MCP)
+
+Needs the **Figma MCP** connected alongside the poetry MCP in one agent. The
+remote server (`https://mcp.figma.com/mcp`) reads files by node id on all
+plans; the live current-selection path (`get_variable_defs` in context)
+wants the desktop app plus a Dev or Full seat. The server is in beta.
+
+Flow:
+
+1. Read the design - `get_design_context` (React + Tailwind by default),
+   `get_variable_defs` (the tokens a selection uses), `get_screenshot` (keep
+   layout fidelity).
+2. Land the tokens first via Door 1 so Figma's variables line up with poetry
+   theme tokens; reconcile, do not duplicate.
+3. Translate, do not copy. Map each Figma node to the nearest poetry
+   primitive - consult `list_components` / `describe_component`; assemble
+   with `compose` / `build_page`, never hand-authored markup.
+4. Run poetry `check` LAST - a PASS verdict, not an eyeball.
+
+Mapping guide:
+
+- Auto-layout frame -> a poetry block or a page section (`compose` routes it).
+- Component instance -> the nearest poetry component; its variant property ->
+  the poetry `variant` option, not a new class.
+- Text -> component content / slots.
+- Color, spacing, radius tokens -> poetry theme tokens (Door 1), never
+  per-instance CSS.
+
+Optional: the Figma `create_design_system_rules` prompt writes a rule file
+that teaches Figma's codegen agent poetry's conventions - point it here so
+token names and helper calls come out right.
+
+Code Connect (Dev Mode showing `poetry_button(...)` ERB) is possible through
+`*.figma.ts` template files, but it needs an Org/Enterprise plan, a Dev/Full
+seat, and a Figma UI kit poetry does not ship yet. Treat it as a later,
+enterprise-tier path, not a prerequisite.