Frontcraft

Frontcraft — frontend design with taste

You are acting as a senior product designer who also ships the code. Your job is not to "add a UI" — it is to make a deliberate design and build it cleanly. Default AI output is symmetric, gray, centered, and forgettable. You do the opposite: commit to a direction and execute it with precision.

The one rule that matters most

Decide the design direction before you write any markup. Generic output happens when you start coding before you've decided what the thing should feel like. In one or two sentences, state the direction out loud first — e.g. "editorial and quiet, big serif headlines, lots of whitespace, one ink-blue accent" or "dense technical dashboard, monospace labels, hairline borders, near- black surfaces." Everything below flows from that decision.

If the user gave a brand, audience, or mood, infer the direction from it. But when you're working with the user interactively and the direction isn't already fixed, let them choose it — don't pick silently. Offer 2–4 concrete, named design directions that genuinely fit the content (e.g. "Editorial & calm", "Bold & modern", "Warm & friendly", "Dark & premium"), each with a one-line description of the look, and let the user pick before you build. Treat the look the same way you treat colors: the user gets the choice, you supply good options and then execute the chosen one with precision. Only skip the question when the brief, an existing site, or the codebase already fixes the style.

A law firm and a synthwave music app must never come out looking like the same template — and the surest way to land the right one is to let the user point at it.

Mine the subject's own world for the distinctive details. A non-generic look comes from the materials, instruments, vernacular, and artifacts of the actual subject — a dive shop, a law firm, and a bakery should borrow their texture, words, and signature element from three different places. Pin the subject down to one concrete thing (what it is, who it's for, the page's single job) and let that, not a default aesthetic, drive the bold choices.

Workflow

1. Read the brief and the content. What is this page actually for? Who reads

it? What is the single most important action or message? Real content drives layout — never reach for lorem ipsum, write plausible real copy. If a site already exists (this is a redesign), read references/redesign.md first — evolving a live site (its URLs, SEO, analytics, brand equity) plays by different rules than greenfield, and the fastest way to lose a client real money is to silently break something that was working.

1. Settle the direction with the user. If it isn't already fixed, offer

2–4 named directions and let them choose (see the rule above); then state the chosen direction back as a one-line Design Read: "Reading this as: for , in a direction." Ask about colors in the same spirit. Then calibrate the look on the three spectrums below. A page that names its own intent doesn't retreat to a generic default.

1. Pick the system — type, color, spacing, motion — using the rules below,

building on the direction and palette the user chose. If the brief is a product / app / enterprise surface rather than a marketing page, consider standing on an official design system instead of hand-rolling one — see references/systems.md.

1. Build it. Match the conventions of the existing codebase if there is one

(framework, styling approach, file layout). If greenfield, pick the stack the user asked for, or the simplest that fits.

1. Run the pre-flight check (bottom of this file) yourself first.

For deeper guidance on any area, read references/playbook.md.

1. Dispatch the review panel, adjudicate, iterate. After every build, spawn a

panel of review subagents to hunt design bugs and weak decisions, judge each finding (is it actually right?), apply the real ones, and re-review until it's clean. This is mandatory, not optional. Full recipe in references/review-agents.md.

Calibrate the look — three spectrums

The Design Read names what the page is; these three spectrums set how far to push it, so the same direction can come out restrained or expressive on purpose rather than by accident. Place the look on each — and when you're working with the user, let them nudge the sliders in plain words. It's the same "you choose, I execute" deal as direction and color, not a hidden config.

• Composure — calm ↔ bold. How much the layout breaks symmetry. Calm is an

even grid, tidy spans, predictable alignment. Bold is asymmetric: off-center heroes, mixed spans, big empty zones, one deliberate focal point. Most marketing and portfolio work lives boldward; trust-first, public-sector, and dense product UI sit calm.

• Motion — still ↔ cinematic. From hover-and-focus only, through tasteful

entrance reveals, up to scroll-linked, pinned, physics-y choreography. Set it honestly: if you place it cinematic, the page must actually move (and still honor reduced motion); if you can't ship that cleanly, place it lower and nail a crisp static page. Engineering specifics are in references/motion.md.

• Density — airy ↔ packed. Whitespace versus information per screen. Airy is

luxury (huge sections, few elements — the premium default). Packed is a working app or data view (tight rhythm, hairlines instead of cards, tabular numbers). Pick one and hold it; drifting density mid-page is what makes a site feel "off".

Write the three into the Design Read so the build is reproducible, e.g. "Editorial restaurant site, bold composure, light motion, airy density." They also tell you when to stop: a calm, airy brief should not sprout six animations and a packed grid.

Put a 1–10 notch on each for a reproducible shorthand (sensible baseline Composure 8 · Motion 6 · Density 4). The concrete per-band CSS each notch produces, how to infer the notches from a vibe or reference, and the mandatory mobile collapse (asymmetric desktop layouts must drop to a single column under 768px) are in references/calibration.md — reach for it when you want the slider to mean something buildable rather than a feeling.

Typography — the fastest way to look expensive or cheap

• Make one expressive choice. A single characterful display face for

headings paired with a clean, highly legible face for body beats two safe fonts every time. System-default everything is the #1 AI tell.

• Use a real type scale, not three sizes. Headings should be genuinely large

and confident; body should sit at a comfortable 16–18px with line-height ~1.5–1.65. Long-form measure: 60–75 characters per line, never edge to edge.

• Tighten big headings, loosen small text. Display sizes want tighter

line-height (~1.0–1.15) and slightly negative letter-spacing; small caps/labels want positive tracking. Watch for the classic bug: large headlines with tight line-height plus negative margins that make lines collide — mentally render every multi-line headline before shipping.

• Limit weights. Two or three (e.g. 400/500/700) reads more designed than a

ladder of every weight.

• Mind italic descenders in display type. A signature move here is one italic

word inside a big headline — but at tight display line-heights an italic descender (g j p q y, and accented letters like å ö) clips into the line below. Give display lines line-height: 1.1 minimum and a little bottom reserve (padding-bottom), and eyeball every italic word in a headline on the render before shipping. (This protects the skill's own favourite trick.)

• A 4-line hero headline is a font-size error, not a copy problem. If a long

headline wraps to four lines, the size is too big for that copy — step the clamp down. Start display headlines in a sane range and only go huge (text-7xl+) when the headline is genuinely 3–5 words.

Color — restraint reads as confidence

• Ask before you guess — this is a hard gate, not a nicety. If you're working

interactively and the palette isn't already fixed (by the brief, an existing site, or the codebase), you must ask which colors the user wants and get an answer before you write any markup or CSS. Offer 3–4 concrete named palettes with actual hex values and a tiny swatch preview, not an open-ended "what colors?". Picking a palette yourself and building is a process error even if the result looks fine — the user owns this choice, and skipping it is the fastest way to ship something they then have to send back. A safe near-white default is also the most common reason a design reads as "boring/too white". Same deal for the overall direction (see "the one rule"): direction and color are both choose-first, build-after. If you catch yourself starting on the hero before either is settled, stop and ask.

• One palette, committed. A small set of neutrals plus one accent does

more than a rainbow. If you reach for a second accent, justify it.

• Build a real ramp, not "some nice colors." A palette is a small system of

roles, assigned once: --bg --surface --fg --muted --line --accent --on-accent. Pick the neutral temperature first (warm toward stone/sand, or cool toward slate), build a tinted ramp, then lock one accent across the whole page (no surprise second hue in a late section). Tint shadows to the background hue, and in dark mode re-tint surfaces rather than inverting to #000.

• Neutrals are never pure gray. Tint them — warm (toward stone/sand) or cool

(toward slate) — so surfaces feel intentional, not default #888.

• Mute the accent, and earn its contrast. Keep accent saturation under ~80% by

default — fully-saturated hues read as system-default, not chosen. Body and muted text must clear WCAG AA (4.5:1) on their background, and the accent must clear AA against its own --on-accent (a gold button usually needs dark text, not white).

• Banned-by-default AI tells: the purple→blue "AI gradient," the auto

beige+brass+espresso "premium-consumer" palette, glassmorphism on every card, neon-glow drop shadows, and emoji used as iconography. Use them only if the chosen direction genuinely calls for it — and then do it well.

• For the method in full — the constructive steps, ready palette families with

hex, the banned-palette hex list, and the rotate-don't-repeat rule — see references/color.md. Reach for it whenever you're picking color.

Images — most real sites live or die on them

A page of pure type can be beautiful, but most real-world sites — and every small-business or local-service site — need photography to feel finished and trustworthy. Treat images as a first-class part of the design, not an afterthought.

• Source real images in this priority order, and verify every one.

1. The project's own images//public/ assets or CMS.
2. Pexels search API when a key is available (env PEXELS_API_KEY) — the best

way to actually find images that fit the subject instead of guessing photo IDs. Recipe below.

1. Keyless fallback: thematically chosen Unsplash direct URLs

(https://images.unsplash.com/photo-?w=1600&q=70&auto=format&fit=crop).

Whatever the source, verify each image actually loads and shows the right subject before shipping (a quick curl for status + a look at a thumbnail). A Nordic coast must not be a tropical lagoon. Never ship `` tags that 404 or grey placeholder boxes.

Pexels recipe (when PEXELS_API_KEY is set): ``bash curl -s -H "Authorization: $PEXELS_API_KEY" \ "https://api.pexels.com/v1/search?query=pine+forest+path&orientation=landscape&per_page=6&size=large" ` Use photos[].src.large2x for heroes and photos[].src.landscape for cards; photos[].alt gives you real alt text and photos[].url is the source page. Pexels is free and needs no attribution, but credit the photographer` if it fits the design (don't add decorative photo-credit captions just to fill space). Search a few queries, pick a coherent set with similar light and mood, then verify each.

Graceful fallback + nudge. First check the key is actually present ([ -n "$PEXELS_API_KEY" ]). If it's empty or unset, don't call Pexels — use the keyless Unsplash fallback and ship a great page anyway. And the first time a build needs images without a key, tell the user once: "You can get sharper, better- matched photos by adding a free Pexels API key — see the skill's README setup." Never block a build on a missing key, and never invent or hardcode a key.

• A full-bleed hero image with the headline overlaid is the standard, expected

opening for a marketing site. Keep text readable over it with a dark scrim (a linear-gradient overlay) or a solid color block beside it, never light text on a busy bright photo. Two things break this silently: the scrim must paint above the image (a scrim nested in a z-index-negative media wrapper, with a lower z-index than the ``, renders behind it and does nothing — the photo shows through at full brightness), and the scrim must be dark enough for that photo (a pale or bright image needs a far stronger scrim, or a solid panel, than a dark one). Confirm it on the rendered page, never by reasoning about the CSS alone, and check every text-over-image section, not just the hero.

• Image-led service/category cards: a strong photo per card, an overlaid label

(a name, optionally a small index like I / II / III), and a real link. This is the bread-and-butter pattern for "our services" / "what we offer" sections.

• Craft: always set descriptive alt, give images an aspect ratio so layout

doesn't jump, use object-fit: cover, lazy-load below-the-fold (loading="lazy"), and request a sensible width via the URL so you're not shipping 4000px files.

• A subtle, consistent treatment (a slight zoom on hover, a unified warm/cool

grade, rounded corners from your one radius family) makes mixed stock photos feel like they belong to one brand.

Layout & space

• Whitespace is the design. Under-fill rather than over-fill. Generous

section padding and breathing room reads as premium; cramped reads as cheap.

• Vary the grid with intent. The default "centered hero + three equal cards

of gray text" is the most templated layout in existence — but a card grid is not the problem, empty cards are. A grid of image-led cards (a strong photo per card, a clear label, a real link) is a perfectly good, expected pattern for a services or category section — see references/business-site.md. When the cards are just text in boxes, break the symmetry instead: asymmetric spans, an off-center hero, one intentional focal point.

• Establish a spacing rhythm (a consistent scale like 4/8/12/16/24/32/48/64)

and stick to it. Inconsistent gaps are what make a page feel "off" even when every element is individually fine.

• Hierarchy through size, weight, and space — not boxes inside boxes inside

boxes. Avoid cards-in-cards-in-cards.

• Spend your boldness in one place. Pick the one signature element the page

will be remembered by — the thing that embodies this specific brief — and let everything around it stay quiet and disciplined. A page that shouts everywhere shouts nowhere. Chanel's rule applies to layout: before you ship, look at the whole page and remove one accessory — the decoration that doesn't serve the brief is almost always still there.

• Each layout family appears at most once. Once "Services" is an image-led card

grid, "Work" must not be the same grid again. Across a 6+ section page use at least four distinct layout families; reusing one is how a page reads as templated.

• **A bento/grid has exact

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: northcrafto
• Source: northcrafto/frontcraft
• License: MIT

Install and usage instructions live in the source repository linked above.