agentleFS
robotostudiorobotostudio/turbo-start-web-agent/.agents/skills/design-a-block/SKILL.md

design-a-block

Skill4 starsChanged 47 days agoMITView on GitHub

Use before writing or editing any component under src/components/ — a new Block, a change to how an existing one looks, an animation, a layout change, or anything a visitor will see. Use whenever asked to design a section, restyle something, "make it look like", add a UI element, or when a request cannot be met by composing existing Blocks. Not for editing content — that is compose-page.

The file

We split this skill into the rules it gives an agent

4 rules. About 0 are common, 0 are distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    /blocks-gallery: every Block rendered live, then the button primitive across every variant and size, the type scale, SectionHeader's …

    line 25
  2. Very specific:

    Put <LedgerCorners /> in a relative wrapper for the crosshairs, or <LedgerCorners away /> when the tiles sit in a gap (Gallery).

    line 155
  3. Very specific:

    When CSS cannot do it (animating to an unknown height, the texture), use the enhancer pattern above and check prefers-reduced-motion in the …

    line 219
  4. Very specific:

    Run pnpm run checks, the same gate CI runs.

    line 245

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Designing inside an existing system

This site is not a blank canvas. Every Block is assembled from the same small set of decisions: eight type roles, one section rhythm, one button primitive, three families of colour tokens, and a handful of shared parts (the ledger grid, the texture bed, the card frame). The reason a page of nineteen unrelated Blocks looks like one site is that none of them invented their own.

Designing here means finding the decision that already exists. The failure mode is not ugly work; it is plausible work that quietly adds a ninth type size, a second button treatment, or a rounded card among square ones, none of which look wrong alone and all of which make the system a little less true.

The mechanics of adding a Block (schema, component, registry, catalog) are AGENTS.md §4. This skill is the part §4 does not cover: what to reuse, and what not to introduce.

Look before you build

  • /blocks-gallery: every Block rendered live, then the button primitive across every variant and size, the type scale, SectionHeader's slots, and the texture. If something like your task is already there, use it.
  • /style-guide: the same system written down, with the same specimens.
  • The Paper file ("Harbour", page 1-0): the design every Block was measured from. A new Block is designed there first, as an artboard in the same language, and built only once it is approved.

Then read the Block whose shape is closest to yours. The conventions are more legible in a file than in any list.

Prefer a variant to a new Block. Hero takes variant: "showcase" | "centered" | "left" (showcase is the default and what home uses) rather than existing three times. A layout that differs by alignment, column count or emphasis is a variant. A Block earns its own entry only when the content it accepts is genuinely different: different props, not different CSS.

Type

Eight roles, defined as --text-* in src/app/globals.css. Pick one; never a bare Tailwind size for something a role covers.

RoleSizeFor
text-display64/70The page title: Hero, the /blog heading, a post's h1
text-statement52/62A closing statement: the CTA band, Newsletter
text-title36/44A section title (SectionHeader)
text-subtitle22/30An item title inside a section: FAQ questions, grid cells, plan names
text-lede18/28The line under a title
text-stat60/64A figure: Stats, a plan price (both at font-light)
text-eyebrow12/16, 0.14emMono small caps: eyebrows, column labels, roles, periods
text-label10/14, 0.14emThe footer's column headings only. Not for anything read as prose
  • Weight is not in the tokens. Titles are 400, the inherited default. The old font-semibold tracking-tight title is gone; do not bring it back. The one exception is text-stat, set at font-light.
  • Step down on small screens with a Tailwind size, then take the role. 64px is most of a phone's width per word, so large roles start smaller: text-5xl lg:text-display, text-3xl sm:text-title lg:text-statement.
  • Body copy is text-base (16px), at leading-6.5 where it sits in a ledger.
  • --text-wordmark-* is a separate family for LogoCloud's placeholder wordmarks only (logo-wordmarks.tsx). Nothing else uses it.

Colour

Tokens only: bg-primary, text-muted-foreground, border-ledger-rule. Never a hex code in a component, never a palette class like bg-zinc-400. A retheme is an edit to globals.css and nothing else, and that holds only while every Block names tokens.

Three families:

  • Base (the shadcn contract): background, foreground, primary and friends. Text runs in three tiers: foreground, muted-foreground, and subtle-foreground. The third tier is for mono indexes, labels and chrome; at 3.7:1 it is not for body copy. primary-foreground is near-black on purpose, because white on the accent fails contrast.
  • ledger-*: the hairline grids and their parts (ledger-rule, ledger-tick, ledger-meta, ledger-meter*, ledger-wordmark*). They exist because the nearest base tokens were close but not equal to the comp.
  • mock-*: only for the UI drawings inside FeatureRows and PreviewStage.

The theme is dark only: color-scheme: dark, and a dark: utility never applies. The ledger and mock tokens are white-on-dark alphas, so a light retheme must set them too.

Rhythm

A Block is <section> wrapping <div className="page-inset">. page-inset is the only horizontal measure (90rem, gutters 1.5rem, 3rem from lg); a Block that sets its own max-w-* container will not line up with the one above it.

Vertical rhythm is py-16 lg:py-22 (64px, 88px from lg). Stats, LogoCloud, PostGrid, ImageCards and PreviewStage sit tighter at py-16, because the comp draws them that way. Measure against the comp; do not guess.

A full-bleed band (the Hero's texture, PreviewStage's stage, the CTA and Newsletter beds) draws its bed outside page-inset as an absolutely placed layer, then keeps its content inside a page-inset as usual.

Shape and elevation

  • Square: cards, frames, image tiles and ledger cells. Square corners with a hairline (outline outline-ledger-rule). No rounded-lg card, no hover zoom.
  • Fully rounded: buttons, pills and the eyebrow tick.
  • Radius (--radius) is only for the UI mock drawings, images inside prose, and small inline marks: the quote avatar (rounded-md) and the highlight behind quoted words (rounded-xs).
  • Shadows are tokens: --shadow-button and --shadow-button-primary (both already inside buttonVariants), --shadow-prompt-card, --shadow-stage-window, --shadow-stage-float. Use them by name, shadow-(--shadow-stage-window); do not write a new shadow.

Buttons and links

  • A link that looks like a button is ButtonLink (src/components/ui/button-link.tsx), which defaults to size="marketing". variant="default" for the primary action, variant="outline" beside it.
  • A real <button> (a form submit) takes buttonVariants() directly, as Newsletter does.
  • Never import ui/button.tsx into a Block. It is a client component, and a Block is a server component.
  • A text link that is not a call to action is TextLink (src/components/ui/text-link.tsx): the label with a chevron, as FeatureRows, PostGrid and the FAQ's contact line use.

Section headings

SectionHeader (src/components/blocks/section-header.tsx) takes eyebrow, title, meta (a note opposite the title) and lede. SectionHeaderSplit beside it sets the lede opposite the title, bottom-aligned, as the ledger sections do.

Eyebrows are part of the system. An earlier version of this skill banned them; the redesign reversed that, and the reason is recorded in section-header.tsx. The rule that survives: an eyebrow says something the title does not. "OUR FEATURES" above "Our features" is noise. The eyebrow is an optional prop on most Blocks, and required on LogoCloud, which has no title.

Hand-roll a header only when there is no title (the LogoCloud precedent), and then copy SectionHeader's tick and label exactly.

Patterns

Each has a reference file. Compose these rather than redrawing them.

  • Ledger grid (ledger.tsx; used by FeatureGrid, Team, Pricing, Stats, LogoCloud). The container owns border-t border-l and each cell its own border-r border-b, all border-ledger-rule, so no two rules ever stack. Put <LedgerCorners /> in a relative wrapper for the crosshairs, or <LedgerCorners away /> when the tiles sit in a gap (Gallery). Close a short last row with ledgerFillers(count, { base, md, lg }), rendering each as an aria-hidden <li>, and tell authors the count that fills cleanly in the schema's .describe().
  • Mono index (FeatureGrid, FAQ, FeatureRows): String(index + 1).padStart(2, "0") in font-mono text-xs tabular-nums tracking-widest text-subtle-foreground, aria-hidden, since the list already announces its order.
  • Texture (src/components/texture/grid-field.tsx). GridField is a primitive, not a Block. preset is dense or coarse. animate defaults to true; pass false for a still bed that ships no JavaScript. pointer (cursor glow) is for the Hero's one large placement only. tile={{ width, position }} fixes the cell size for a small bed (never animated). The texture masks bg-foreground, so it follows a retheme.
  • Beds (src/components/site/site-mark.tsx). Fade a texture into the page with groundAt(alpha), BED_VIGNETTE and EdgeScrims: every stop is --background at an alpha, set as an inline backgroundImage because a gradient of token colours has no canonical class.
  • Card frame (src/components/content/card-image.tsx). CardImage is an image in the shared 4:3 square frame on the hairline; cardFrame is the frame alone. PostCard, ImageCards and FeatureSplit share it.
  • Ledger marks (ledger-marks.tsx). CheckMark for the recommended side (text-primary) or a plain list (text-muted-foreground), DashMark for the alternative. Both are aria-hidden.
  • The recommended choice (Comparison's column, Pricing's emphasized plan): a lifted bg-foreground/3 panel under a 2px bg-primary rule, pink checks, and the primary button. Pink appears once per section, for that choice.
  • Interactive without JavaScript (faq.tsx with faq-motion.tsx). The server renders native HTML that already works: <details>/<summary>, styled by state with group-open:. A small client component may enhance it (the FAQ's animated height), respecting prefers-reduced-motion. If the enhancer never loads, nothing breaks. This is the template for anything interactive.
  • Brand-coloured strip (banner.tsx). The one Block drawn on bg-primary, for an in-page callout. Not the site-wide announcement bar, which is chrome in content/settings/announcement.yml.

Rules that have not changed

No arbitrary values. p-[13px], text-[#4a4a4a], w-[347px] bypass the rhythm and the tokens, and the class you want usually exists: py-8.5 is 34px, lg:w-95 is 380px, opacity-16 is 16%. Canonical Tailwind classes only.

Never write the site's name. It lives in content/settings/site.yml and is read from site in #velite (see src/app/layout.tsx, and Comparison's default column label). pnpm run brand:check fails on it, including inside an sr-only caption.

Server components by default. A Block ships client JavaScript only when it genuinely needs it, and then as an enhancer over working HTML (above).

Measure against the comp. Record measured values in a comment, and when the nearest token is close but not equal, add a named token rather than rounding by eye; that is how the ledger-* family arrived.

Motion

CSS first, gated on the visitor's setting: motion-safe:animate-*, never an unconditional animate-*. Where a loop duplicates content to run seamlessly, the duplicate is aria-hidden="true" and motion-reduce:hidden. Check globals.css for an existing keyframe before writing one: --animate-marquee is there, used only by the announcement bar.

When CSS cannot do it (animating to an unknown height, the texture), use the enhancer pattern above and check prefers-reduced-motion in the script.

Markup that passes the gate

pnpm run checks runs biome, and its accessibility rules are not advisory. A list is <ul> and <li>, not a <div> with role="list"; the ledger grids are lists.

Images use next/image: explicit width and height, or fill inside CardImage or another sized frame, with sizes matching the layout. Decorative images take alt=""; an image that carries meaning takes a real description.

A Block is not finished until the gallery shows it

pnpm catalog writes an empty stub for a new Block so the generator can run mid-work. Fill it in with a real usage example in content/pages/blocks-gallery.mdx, including an eyebrow if the Block takes one, and drop the status="todo". Use the copy you would actually ship; the gallery is where the next person decides whether to reuse your Block.

pnpm run checks fails on a Block with no example.

Before you deliver

Run pnpm run checks, the same gate CI runs. Then look at the page at 1440, 768 and 375, beside its artboard. A Block can validate, typecheck, build, and still be half a rhythm out from the one above it. Where you have a browser, open it. Where you do not, serve the build and assert on the HTML.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.