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.
In this repository15 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- compose-pageSkill
- find-skillsSkill
- humanizerSkill
- no-em-dash-copySkill
- sync-changesSkill
- write-a-skillSkill
- compose-pageSkill
- design-a-blockSkill
- find-skillsSkill
- humanizerSkill
- no-em-dash-copySkill
- sync-changesSkill
- write-a-skillSkill
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
- Very specific: line 25
/blocks-gallery: every Block rendered live, then the button primitive across every variant and size, the type scale, SectionHeader's … - Very specific: line 155
Put <LedgerCorners /> in a relative wrapper for the crosshairs, or <LedgerCorners away /> when the tiles sit in a gap (Gallery).
- Very specific: line 219
When CSS cannot do it (animating to an unknown height, the texture), use the enhancer pattern above and check prefers-reduced-motion in the …
- Very specific: line 245
Run pnpm run checks, the same gate CI runs.
≈ “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.
Files
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.
| Role | Size | For |
text-display | 64/70 | The page title: Hero, the /blog heading, a post's h1 |
text-statement | 52/62 | A closing statement: the CTA band, Newsletter |
text-title | 36/44 | A section title (SectionHeader) |
text-subtitle | 22/30 | An item title inside a section: FAQ questions, grid cells, plan names |
text-lede | 18/28 | The line under a title |
text-stat | 60/64 | A figure: Stats, a plan price (both at font-light) |
text-eyebrow | 12/16, 0.14em | Mono small caps: eyebrows, column labels, roles, periods |
text-label | 10/14, 0.14em | The 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-tighttitle is gone; do not bring it back. The one exception istext-stat, set atfont-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), atleading-6.5where 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,primaryand friends. Text runs in three tiers:foreground,muted-foreground, andsubtle-foreground. The third tier is for mono indexes, labels and chrome; at 3.7:1 it is not for body copy.primary-foregroundis 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). Norounded-lgcard, 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-buttonand--shadow-button-primary(both already insidebuttonVariants),--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 tosize="marketing".variant="default"for the primary action,variant="outline"beside it. - A real
<button>(a form submit) takesbuttonVariants()directly, as Newsletter does. - Never import
ui/button.tsxinto 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 ownsborder-t border-land each cell its ownborder-r border-b, allborder-ledger-rule, so no two rules ever stack. Put<LedgerCorners />in arelativewrapper for the crosshairs, or<LedgerCorners away />when the tiles sit in a gap (Gallery). Close a short last row withledgerFillers(count, { base, md, lg }), rendering each as anaria-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")infont-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).GridFieldis a primitive, not a Block.presetisdenseorcoarse.animatedefaults to true; passfalsefor 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 masksbg-foreground, so it follows a retheme. - Beds (
src/components/site/site-mark.tsx). Fade a texture into the page withgroundAt(alpha),BED_VIGNETTEandEdgeScrims: every stop is--backgroundat an alpha, set as an inlinebackgroundImagebecause a gradient of token colours has no canonical class. - Card frame (
src/components/content/card-image.tsx).CardImageis an image in the shared 4:3 square frame on the hairline;cardFrameis the frame alone. PostCard, ImageCards and FeatureSplit share it. - Ledger marks (
ledger-marks.tsx).CheckMarkfor the recommended side (text-primary) or a plain list (text-muted-foreground),DashMarkfor the alternative. Both arearia-hidden. - The recommended choice (Comparison's column, Pricing's emphasized plan): a
lifted
bg-foreground/3panel under a 2pxbg-primaryrule, pink checks, and the primary button. Pink appears once per section, for that choice. - Interactive without JavaScript (
faq.tsxwithfaq-motion.tsx). The server renders native HTML that already works:<details>/<summary>, styled by state withgroup-open:. A small client component may enhance it (the FAQ's animated height), respectingprefers-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 onbg-primary, for an in-page callout. Not the site-wide announcement bar, which is chrome incontent/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.
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
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.

