Codex

The law for the layout library — the shelf a finished material is paired with. It sits beside card-design-language.md, which governs how one card earns its surface; this document governs a narrower thing: a card or poster whose only open slot is the GROUND under it. The kit is src/components/compositions/ (a contract, a frame, a ground slot — deliberately nothing more); the layouts live under src/app/(workbench)/labs/compositions/layouts/ and register once in registry.ts; the living example is /labs/compositions, a full-screen pairing workbench — the composition on stage, materials beneath it, and a visual layout library beside it. The (workbench) route group opts out of the app shell without changing the public URL.

A shader is a material, not a work. So is a photograph, a gradient, a video. Graphic and interface design have always been "pick the layout, swap the ground", and the ground has always been allowed to be anything a material can be — except a shader, whose cost kept it out of the sequence. The cost is gone; the sequence is what this library supplies. A good shader alone is a demo. A good shader under a layout whose type stays legible over it is a piece, and a shelf of such layouts is what lets a family of shaders become a body of finished work rather than a folder of effects.

The library is therefore a CATALOGUE, not an editor. A layout is a fixed design — brought in one at a time, re-originated in the house language, its geometry and copy decided — with one thing left open. Geometry and copy remain fixed. Readers choose the ground and tone; Spot Card and Profile Card additionally expose one shared gradient-curve parameter, explicitly requested as a bounded exception to the no-knobs rule. It shapes the existing scrim without moving its start, end or content.

The first question is what the reader wants to make. Type answers that question (Hero, Profile Card, Spot Card, Metric Card). A preset is one fixed design within that type (Hero → Split, Editorial, Centered). Types are not component shells: presets in the same type may have different geometries and anatomies. A profile card with one preset is still a type; selecting it loads that design immediately, without a redundant second picker. A multi-preset type exposes its designs as thumbnails, rendered from the same components with neutral static grounds. There is no separate thumbnail geometry to drift.

Material and tone are independent choices. Switching type or preset preserves both. A preset belongs to exactly one type and registers once in the flat registry (type + preset); grouped shelves and counts derive from it. Empty types are not offered. Adding a second Profile Card preset automatically turns its single-design readout into a visual shelf; it requires no page edits.

Classification remains three orthogonal facts about each design. Anatomy still governs implementation, but it is no longer the primary browsing filter:

Hero is a use type, not a synonym for 16:9. A future portrait Hero can have its own frame without creating another category. Conversely, two 16:9 designs do not belong together merely because their dimensions match.

The three anatomies, and what each owes the type:

• Bleed — the ground fills the frame; the content sits on a SCRIM that fades from the card's surface into the material, solid where the words stand, gone where the ground shows. Hero sections and the X-style profile card. The scrim is the layout's responsibility: a photograph is one exposure and a scrim can be tuned to it once, but a shader changes every frame, so the scrim has to be solid under the type, not merely dark enough for one picture.
• Panel — the frame is cut with a hard edge; the ground owns one region and the content the other, on solid surface. No scrim, so the ground can be as busy as it likes — the anatomy for a material meant to be looked AT rather than through.
• Inset — the content owns the frame and the ground appears in framed windows: a thumbnail, a swatch, a well. Small footprint is the point — the one anatomy under which a page can hold several live grounds at once.

A layout that fits none of the three is a new anatomy, and a new anatomy is legislated here before its first layout is filed.

Every layout obeys these; they are what make the shelf read as one product.

• Achromatic, by law. The content layer has five colours per tone — surface, ink, muted ink, a hairline, one chip — and no hue. Hue is the ground's. This is what makes a shader, a photograph or a gradient the palette of the piece by construction. Even the one action is black-on-white or white-on-black; the brand token does not appear on a composition.
• Concrete values, not tokens. The palette is hex, for the reason the cover engine's is: a composition is an artifact that travels — a PNG, a video, a frame in someone else's feed — so its colours are content, and content does not reference a stylesheet it will never ship with. The frame's EDGE is concrete for a second reason: a composition stands on a stage over scenery, never on the app's own background, and the page's card tokens flatten to a hairline in dark mode precisely because a card there has nothing to cast onto. A composition does — so the frame carries its own elevation (ELEVATION), pure shadow in light and shadow plus an INSET hairline in dark, and its radius is cqmin like everything else inside.
• Sized in cqmin. Every length inside the frame is a hundredth of the frame's short side. A layout is the same layout at 320px and at 1080px, which is what an export needs. The frame's container type is size for this; its aspect ratio supplies the height.
• One layer between ground and type. A Bleed layout's scrim is a gradient from the surface to nothing; a Panel layout has no layer at all. Never backdrop-filter, never a mask over a live canvas, never a second translucent layer: a frosted pane re-samples the most expensive layer on the page every frame, and the scrim samples nothing.
• Light and dark are one layout. The geometry is identical; only the surface and the ink flip. A -dark twin is a second copy of one decision.

A ground is handed { width, height, tone, reducedMotion } and returns pixels into the box. That is the whole interface, and its narrowness is the point:

• A layout never branches on the material. Five renderers live behind one Ground component; the layout mounts it and moves on.
• A shader is a component that satisfies the same contract, so the fifth material can arrive from another repository through whatever seam the two agree on, without a layout changing. Until it does, the slot is proved by a stand-in (drift-ground.tsx, a CSS conic gradient turning under a blur) that exercises measurement, tone and reduced motion; it is there to be replaced, not extended.
• Reduced motion is the ground's to honour — a video pauses on its first frame, a shader stands still — and tone is passed so a live ground can choose its deeper palette for a dark surface rather than merely darkening.
• A project with no shaders runs the same layouts on photographs and gradients. The library radiates because the seam is narrow.

The workbench lives outside (app) in (workbench)/labs/compositions; the URLs /labs/compositions and /labs/compositions/<slug> stay intact. It is a catalogue workbench under workbench.md: a toolbar, stage and library, with a bounded scrim adjustment for opted-in designs rather than a full property inspector.

• The toolbar carries the return to Labs, a global theme toggle, and a copy-link action. Theme affects the interface; composition tone affects the artifact, and the two are independent.
• The stage takes the remaining viewport. Its size container fits the composition by both available width and height, retaining its fixed aspect. The shared Continuum scenery stays behind the artifact.
• The material strip stays below the stage, scrolls horizontally, and displays labelled stills. Shader presets carry a still; video presets display their poster. Only the stage mounts a live ground.
• The library is a right-hand rail: Type, then a visual preset shelf, then composition tone and, for opted-in presets, Gradient curve. Anatomy, subject, frame and attribution are secondary facts in a collapsed Design details section. This is a picker, not an inspector: it loads whole designs and never edits their geometry or copy.
• Desktop locks the viewport and scrolls the rail internally. Narrow screens put the stage and material strip first, then the library in document flow.
• The URL is the pairing document: the path identifies the preset; material, tone and curve query parameters preserve the combination. Selection updates native history (integrated with Next's pathname/search hooks), so Back, Forward and refresh restore the same pairing without a second store. Curve previews are local only during a slider gesture; release commits one history entry. Invalid curves fall back to 100; finite values clamp to 0–100. Unknown material/tone values fall back to a known material and dark tone; unknown preset routes return 404. Old Profile Card and Metric Card links still work.

Spot Card and Profile Card share EasedScrim and one gradientCurve prop. Registry metadata opts a preset into the control; Hero and Metric Card do not show it. The strength is 0–100: zero gives t, 100 gives smoothstep t²(3 − 2t), and intermediate values blend the two. One pure function drives both the visible curve and 33 sampled CSS opacity stops. Endpoints stay at 0 and 1, the fade stays monotonic, and no mask, blur or extra overlay is added. The initial strength is 100. Linear/Eased buttons provide exact endpoints; the slider supports continuous preview and keyboard adjustment. The setting persists when changing type, material or tone and is included in copied links.

Each layout still owns its geometry: Spot Card fades from 15% to 75% of its portrait height, following the supplied Jhey reference; Profile Card keeps its existing fade interval (42% to 76.8% of its 3:2 frame height). Thumbnails use the preset default. Reference-only comparison cards, underlay toggles and stop guides are not part of the catalogue; the curve preview explains the single parameter directly beside the selected artifact.

The intake is the same shape as filing a card in /labs/cards: one file, one registry line, no page edits.

1. Re-originate, don't copy. The reference is content: keep its information architecture and its signature geometry, translate its colours into the achromatic palette, replace its copy with original mock, and record the source in after.
2. Classify before you build. Choose the use type and a preset name. Then anatomy — where does the ground sit, and what does that oblige (a scrim, a panel edge, wells)? Then subject, then the one frame it was designed for.
3. Compose the kit. Frame for the container, Ground for the slot, the palette for every colour, cqmin for every length. A Bleed layout writes its own scrim (direction, reach, where the action rides); a Panel layout its own cut.
4. Check it on the worst ground. The picker's shader stand-in and the busiest photograph, in both tones. Type that reads over those reads over anything.
5. Register. One entry in registry.ts. The shelf groups it by type; its preview, count and deep link follow automatically.

• A layout that knows its ground. A component that branches on ground.kind, or a scrim tuned to one photograph. The library stops radiating the moment a layout needs to know what it holds.
• Hue on the content layer. A brand-coloured action, a tinted hairline, a coloured avatar ring. The ground was the palette; now there are two.
• A frosted pane. backdrop-filter over a live canvas.
• Two tones, two layouts. A profile-card-dark beside profile-card.
• A destination as a category. A "Stories" folder holding copies of every layout at 9:16. Destinations alias frames.
• Unbounded knobs. Apart from the explicit scrim-curve exception above, a reach slider, an anchor picker, a content editor. The moment a layout is parametric it is a generator, and a generator's output is the whole parameter space — which is mostly not good. The shelf holds decisions, not ranges.
• A grid of live grounds. Twenty shaders in a picker is twenty WebGL contexts and a killed tab. Swatches are stills — a shader preset carries one, a video preset shows its poster — and exactly one ground is mounted live, on the stage. Inset is the anatomy for several small live grounds on one surface.