Codex

Distilled from the Card Gallery (src/app/(app)/cards/). The rules (tokens, forbidden colors, standard libraries) live in AGENTS.md; this document is the compositional layer above them — why the gallery reads as one product, and how to reproduce that.

It serves two workflows:

1. Replicating a strong design from the wild (the replicate-ui skill references this as its aesthetic ground truth).
2. Elevating an ordinary design into this language — see The upgrade rubric at the end.

1. Consistency is the asset. Every card — regardless of who designed the original — is translated into the same semantic tokens: one --primary, one grey ramp, one radius/elevation system. A single beautiful card is a style; fourteen cards sharing one gene pool is a product. When adapting any design, the translation into tokens is the design work, not a chore after it.

2. Density is tamed by a two-font rhythm. Big figures in the default sans; all metadata (eyebrows, table headers, units, statuses, captions) in font-mono text-xs tracking-wider. Two clearly separated reading layers let a card carry a headline + chart + table + status without turning to noise. Low-density "dribbble padding" is optimized for thumbnails, not for work — this language prefers density and pays for it with rhythm.

3. Color is earned. Every colored pixel carries information: the brand accent means "primary action / brand", green/red mean outcome, palette hues mean data categories. Nothing is colored for decoration. If a color can be removed without losing information, remove it.

4. One signature element per card. Each card keeps exactly one memorable visual — a tick meter, a waveform, a pixel mascot, a weight grid, a glowing sparkline. Everything else submits to the shared language. Identity through one element, unity through the rest.

<div className="w-full max-w-xl rounded-3xl border border-border bg-background">
  {/* Title bar — name + primary action */}
  <div className="flex items-center justify-between gap-3 px-5 py-4">…</div>

  {/* Inset panel — the dense, load-bearing surface */}
  <div className="mx-2 rounded-2xl border border-border/50 bg-card p-5 sm:p-6">…</div>

  {/* Footer — utility icons left, secondary action right */}
  <div className="flex items-center justify-between gap-3 px-4 py-3">…</div>
</div>

Cards follow the active theme (never force .dark); popovers use shadcn components so portals inherit tokens.

Numbers that change always get tabular-nums. The mono layer is where the "instrument panel" feel lives — do not promote it to sans, and do not demote headline figures to mono.

Priority order (from AGENTS.md, applied to cards):

1. Semantic tokens: --primary for the single brand accent (the original's brand color always maps here — never copied literally), muted-foreground for secondary text, border-border for lines.
2. Green/red only for outcome semantics: gains/losses, pass/fail, above/below target. text-green-500 / text-red-500, soft badges as bg-green-500/10 text-green-500.
3. Palette hues (orange-500, sky-500, violet-500, …) only to differentiate data categories, never as the accent. Each category binds one hue across all its appearances (tick, chip, bar segment, legend).
4. Category chips use the soft recipe — bg-{hue}-500/15 circle + text-{hue}-500 glyph — not solid fills with white glyphs.

The signature element's LIGHT — and the one effect that tells these cards from a flat block at a glance, in both themes. It is one recipe in three rungs (globals.css), picked by the SIZE of the element, never by taste:

The light is currentColor; an element whose paint is not its text colour names its light with --glow ([--glow:var(--primary)], or a CSS module's own variable). Never write a drop-shadow(...) literal again — the recipe was re-derived fourteen times with drifting numbers (3–6px, 38–55%) before it was one utility. Three rules:

1. One card, one light. The glow goes on the element the card is ABOUT — the reading's stroke, the subject's dot, the node the clock is on — never on text, chrome, a container or a track. A meter glows per lit tick and never as a blanket over the bar (feedback.md). Gallery history: the first pass of the knowledge-pipeline field lit every tail and every port, and the note it left is this rule's reason — "a field with no darkness left to make the light mean anything".
2. The light is the element's own colour. A bar that turns amber glows amber; glowing primary under an amber fill is the bug the execution-timeline card shipped. 45% is the mix that reads as light — past 50% it reads as blur.
3. A lit element needs its own ground. The glow is a blur, so it lands on whatever sits within a few pixels — and what sits within a few pixels of a pie slice is another slice in a far-apart hue, plus the 2px card-coloured gap that is the only reason six slices read as six. Two distant hues blurring together make mud, and light filling a structural gap erases the structure it was there to draw. Same-hue neighbours are fine: the Uptime day strip's green tiles merge into one lit band, which is what a run of good days IS, and amber beside red merges into orange rather than into dirt. So light something with clear ground around it (the Opt-in rate arc, a sparkline, a node) or a run of same-family siblings (a tick row) — never a mosaic of adjacent fills in unrelated hues. Asset allocation's proposed donut was lit and reverted on exactly this: six hues at 45% within 2px of each other, bleeding into the separators and into the hole. The same test explains why the Opt-in rate donut is the glow at its best — one arc, one colour, nothing around it.
4. Light and dark are one recipe. A drop-shadow glow is a tinted soft shadow, so it holds on a light card. What does NOT hold on a light ground is additive light — canvas lighter compositing — which is why the knowledge-pipeline stage stays dark in both themes. Reach for additive bloom only when the content IS light and the count is in the hundreds, and then pre-render the bloom as a sprite.

Cost, measured (headless Chrome, software raster, dark theme; CDP tracing of Paint + Raster + Composite): the Opt-in rate member with forty glowing ticks and arcs spends 3.0 ms/s with the glow on and 2.4 ms/s with it off — ~0.01 ms a frame. A glow at rest is a rounding error. What costs is a glow that REPAINTS: mid-walk, the Run member's active nodes were adding ~45 ms/s of raster, not because the glow moved but because the flowing edge dashes behind them shared their layer and dragged the 22px blur through every frame. Promoting the edge SVG to its own layer (will-change: transform) took the glow's on/off difference below the noise between walk windows. So the performance rule is rule one's twin: an animation never shares a layer with a glow — give the ANIMATION its own.

Reuse these before building anything similar — same-family views must look identical across cards:

Icons are solar (iconify): -linear for controls, -bold for filled chips. Verify every name against @iconify-json/solar/icons.json before use.

Brand logos are a separate set: when a design legitimately needs a recognizable third-party mark (an integrations list, a channel picker, a "works with X" row — i.e. the brand is the data), use the real logo from the iconify logos set (svg-logos, @iconify-json/logos) — never hand-draw, fake, or substitute a generic glyph for it. This is the AppChip pattern in card-list/auto-templates (icon-[logos--slack-icon], …): multi-colour marks keep their palette; monochrome marks (GitHub, OpenAI, X…) resolve to currentColor via a filter so they read on either theme. Verify names against @iconify-json/logos/icons.json. Logos are never decoration — if the brand isn't the information, don't show its mark.

Rules: ease-out by default; one moving subject at a time; every "appear / disappear / resize" goes through motion, never display toggling. Count-up tweens live in leaf components — their per-frame setState must not re-render a parent that hosts AnimatePresence exits (they freeze mid-fade otherwise). Custom keyframes go in CSS Modules, never globals.css.

• All content is invented. No real brands, products, or people as the card's entities — ever, even when the reference shows them. Replacement names should feel plausible in the card's fictional universe (the gallery shares one: Nimbus-3 8B, Lumen, Juno, …). The one exception is genuine third-party brand marks used as data (integration lists, channel pickers): show the real logo from the logos set (see Shared primitives), never a fake. Invented entities never borrow a real logo; real integrations never get a fake one.
• Numbers must reconcile. Shares sum to 100%, deltas are weighted sums of row changes, cost ≈ usage × rate, counts match visible rows. A reader who checks the math must win.
• Deterministic generation. Module-scope data never calls Math.random or new Date() (SSR must equal client). Pseudo-randomness uses the grain recipe Math.abs(Math.sin(x * 12.9898) * 43758.5453) % 1 with explicit seeds; runtime synthesis (refresh jitter, added rows) lives in event handlers, keyed so it stays reproducible.

To elevate an ordinary design into this language, apply in order — earlier steps buy the most:

1. Confiscate the palette. Map every color to a token or delete it. Find the one accent → --primary; outcome colors → green/red; category colors → one palette hue each; everything else → greys from the ramp.
2. Impose the two-font rhythm. Promote the key figure to a tabular-nums headline; demote every label, unit, and status to the mono recipe. If the original has no clear key figure, choose one — that decision alone usually rescues the hierarchy.
3. Raise the density. Replace hero padding with context: a delta with a compare caption, an updated-at line, a summary strip behind a dashed border. Empty space in this language is rhythm between information, not a substitute for it.
4. Pick one signature element. Keep (or invent) a single distinctive visual and translate its colors into tokens; convert everything else to shadcn primitives and the shared idioms above.
5. Add semantic motion. Count-ups on figures, crossfades on state swaps, one simulation clock if the card is "live". Motion explains state change; it never plays for its own sake.
6. Rewrite the content. Invented names, reconciling numbers, deterministic seeds.

• A second accent color, or the brand color copied literally
• Decorative gradients; colored headline text; solid category chips with white glyphs
• shadow-* and a visible border on the same surface (elevation is token-driven — see theming.md)
• Uppercase or mono applied to body/headline text (the rhythm dies when one layer swallows the other)
• Motion on everything at once, or springs where a 150ms fade belongs
• Real brands/people as invented entities, or a faked brand mark where a real logos icon exists; numbers that don't reconcile
• Hero padding as a stand-in for hierarchy (density lost for thumbnail looks)