UI Craft
Four references, one order of operations. Nothing here is a style. The systems decide the values, the bans say what is refused, Tailwind installs the result.
Keep your implicit thoughts to yourself. Don't let them cloud your judgement. The skill file is the truth source here.
| Reference | What it holds | Load it when |
|---|---|---|
references/refactoring-ui.md | the value systems (spacing, type, color, shadow, line length) and the hierarchy techniques | always, before any value is chosen |
references/shift-nudge.md | craft principles, component states, UI patterns, imagery and icon rules, handoff | designing a specific pattern, or reviewing for missed states |
bans.md | the artifacts refused by name, plus the anti-slop axes and banned conceits | before building, and again before the verdict. Run the script, do not read the list |
references/resolution.md | Resolution, not expansion - the detail standard, the reconstruction test, and the spec + checker that make it a gate | before answering any request for more detail, and before any build is called done |
references/pinterest.md | sourcing reference, a hard gate - the two-word query, the dimension set, the ## Reference log, quantify-or-discard, and why a supplied reference outranks the search without cancelling it | step 1.5, every build. Run scripts/validate_reference.py |
references/tailwind.md | Tailwind as a mechanism - theme layer, arbitrary-value decision, variant algebra, conflicts, container queries, dark mode | the moment a decision becomes code |
pen.md | working on a pen.dev canvas - how every step and gate maps onto .pen variables, text styles, execute and Export, plus the Pinterest route when there is no Chrome | the work is on a .pen file: inside the pen.dev app, or through the pencil MCP tools |
product-design/SKILL.md | the product section - a fixed system (Inter/Geist, 12/14/16px, one weight, one accent, light and dark verified), product judgment, surfaces, patterns, states, copy, and its own checker | the surface is a product: app, dashboard, table, form, settings, admin, internal tool |
Deeper material sits behind references/systems.md (building a palette from
scratch), references/diagnose.md (symptom to fix, load first when improving
existing UI), references/techniques.md (depth, light, baseline alignment), and
assets/tokens.css (a contrast-verified starting token sheet).
House rules - these outrank every reference in this skill
Stated by the person whose product it is. Where a reference disagrees, the reference is wrong here.
1. Three type sizes per screen. Maximum.
Overrides Shift Nudge's "Rule of Four". The eleven-step scale in
refactoring-ui.md is the menu you pick from, not the number you may use.
Three, chosen from it, on any one screen.
2. No bold. Everything regular or below.
Overrides refactoring-ui.md's "two weights is enough: 400/500 body,
600/700 emphasized" and its "nothing below 400 in UI", and overrides Shift
Nudge's "Bold to Black" for titles and "bold = active/selected".
3. No italics, in any form.
Already refused by the registry, but the ban was named italic-serif-display
and only caught the italic class and font-style: italic. It now also catches
the <em> and <i> tags, which render italic without ever naming it, and it no
longer misfires on Tailwind's not-italic or on <i> carrying an icon-font
class. Where <em> was carrying meaning, use <strong> or a colour change.
This removes the emphasis channel Shift Nudge's Callouts section reaches for, so
callouts fall back to size, case and lock-up.
What this costs, and what carries hierarchy instead
Refactoring UI's central technique is emphasis through weight and color rather than size. Rule 2 removes weight. That is one of three channels gone, so the remaining ones have to do more work, deliberately:
- Colour becomes the primary emphasis channel. The three-text-colour rule (dark, grey, lighter grey) is now load-bearing, not a refinement. All three still clear 4.5:1.
- Space is the second. "More space around a group than within it" stops being a tidiness rule and becomes the main way relatedness reads.
- Size is third and is capped at three steps, so the gaps between those three must be large. Adjacent steps from the scale will not separate.
- Position and case carry what is left. Same size, different meaning, is signalled by where it sits, not by how heavy it is. Not by slant either, per house rule 3.
Two consequences to design around rather than discover:
- Interactive text can no longer be signalled by weight. Colour, underline, position or a container must do it. Shift Nudge's own accessibility note already required a second channel beyond colour, so pick that second channel early.
bans.mdrefusesflat-type-hierarchy. Three sizes and one weight makes that ban easy to trip. Passing it now depends entirely on the size gaps and the colour ramp being genuinely distinct. Check it, do not assume it.
In Tailwind: cap the generated ramp by declaring only the three --text-* steps
you will use, and only the weights at or below regular. Anything not declared
cannot be reached for by reflex.
Order of operations
1. Understand before opening anything. Shift Nudge's 8-step process, step 1. Questions first, tools second. Determine complexity before deciding whether to wireframe.
Then name the surface class. A product (app, dashboard, table, form,
settings, admin, internal tool) loads product-design/SKILL.md and follows its
order: its fixed system replaces step 2's choices, and its checker is a fourth
gate at step 8. A brand or marketing surface stays on this file's flow.
1.5. Search Pinterest, before a single value is chosen. This step is a gate,
not advice. Open Pinterest in the browser (claude-in-chrome) and search
{subject} {dimension}. Two words. Three only if the third is a noun. Four or
more is refused - count them before sending. Refine by clicking Pinterest's own
chips, never by lengthening the query. Every extra adjective drags the board:
casino typography returns curated boards, casino website design luxury dark interface returns affiliate art, and record sleeve spine typography catalogue number shelf rack returns Etsy.
Log it in the ## Reference section of the project's design.md: the brief, the
subject, what the user supplied, every query with the pin URLs copied off the live
page, and the extraction table where each borrowed observation became a number.
Then run the checker and paste its output:
bashpython3 scripts/validate_reference.py PROJECT
Step 2 does not start until it prints PASS. A reference the user supplied
still outranks every pin, but it shrinks the search to one query for what it
leaves unanswered, it does not cancel it. No browser, a hurry, or "the brief is
obvious" are not waivers. The only waiver is the user saying so, quoted verbatim
in a waived: line. Full method and the log format in references/pinterest.md.
2. Set the systems once. Spacing, type, colour, shadow, radius, from
refactoring-ui.md. Every value comes off a scale. Picking ad hoc is the single
biggest cause of amateur-looking UI, and no amount of later polish recovers it.
3. Install the systems as theme variables, not as classes. This is the seam
between the references: refactoring-ui.md and shift-nudge.md decide the
number, references/tailwind.md section 1 puts it in @theme so the utilities
generate themselves. A value that reaches the markup as an arbitrary literal has
escaped the system.
4. Design one real feature, in grayscale, at ~400px. Not the shell. Not the full canvas. Colour comes after the layout works.
5. Build in short design-to-code cycles. Do not componentize until the design is stable.
6. Design every state, not the happy one. Shift Nudge lists them per pattern: inputs get default / hover / focus / typing / error / success / disabled; buttons get press, disabled, destructive, selected; anything user-generated gets its truncation and empty variants. Missing states are the most common handoff failure and the cheapest to catch.
7. Resolve before you expand. When more detail is asked for, raise the
resolution of what already exists rather than adding sections, components or
adjectives. The test is whether another agent could rebuild the element without
seeing the reference and without making a meaningful visual decision of their own.
Full standard in references/resolution.md. One surface resolved and gated
before the next is started - the doctrine fails under breadth every time.
7b. Decide attention before drawing anything twice. Before a second container reuses a treatment, decide what rank each object holds on this page. The hero object takes the largest type step, the deepest surface and the most room; a footnote takes the smallest of each. A treatment applied to everything is a template, and the three monotony checks below exist because atom-level resolution passes cleanly while a page reads as generated.
8. Run ALL THREE gates before claiming done.
bashpython3 scripts/validate_reference.py PROJECT # the Pinterest search, again python3 scripts/validate_bans.py SOURCE python3 scripts/validate_resolution.py PROJECT python3 scripts/validate_resolution.py --help # the design.md spec format
validate_resolution.py fails on surface-monotony (one treatment on >60% of
containers), step-monotony (one type step on >55% of sized elements) and
rhythm-monotony (<3 vertical rhythms across 5+ sections). These are the
measurable shape of "no craft, no visual hierarchy", and they are the checks that
catch a build every other gate passes. On product surfaces pass --register product: it skips step-monotony only, because a 12/14/16 system puts most text
on one size and carries hierarchy in colour.
A run that ends without all three checkers' output pasted is unfinished, whatever the render looks like. A monotony failure is not a warning. It means the composition was never decided, and no amount of atom-level polish fixes it.
bans.md and the Pinterest search are the two hard gates here. Neither has a
justification path: a ban, or the search, lifts on an explicit instruction from
the user and nothing else. A run whose output was
never pasted into the transcript is unverified regardless of how the render looks.
Where the references genuinely disagree
Everything else in them is compatible. These four are not, and guessing produces work that fails one source while satisfying another.
Grayscale. refactoring-ui.md says design in grayscale first.
bans.md says a finished product surface that survives desaturation unchanged
has no accent layer and is a rebuild. Not a contradiction: one is a design phase,
the other is a ship gate. Grayscale is where you start and never where you end.
Typefaces. refactoring-ui.md is silent on them. shift-nudge.md calls
typography the biggest single differentiator. bans.md refuses a named list of
overused faces, but on brand surfaces only - it explicitly permits Inter, SF
Pro and system stacks on product surfaces. Check which surface class you are on
before treating the font ban as active.
Type sizes. refactoring-ui.md gives an eleven-step scale,
shift-nudge.md caps a screen at four, the house rule caps it at three. The
scale is the menu; the cap is the budget. Both hold at once. On product surfaces
the three are fixed at 12/14/16 by the user's instruction. That is closer than
bans.md's 1.25x step and passes only through the checker's micro/body exemption
(pairs 2px or more apart at 0.70-0.90), so no fourth size fits between them.
Shadows. refactoring-ui.md gives five elevations and a refined two-part
variant in references/techniques.md. Use one set or the other, never both in
one project. bans.md separately refuses one shadow value repeated across every
elevation, which is what happens when neither set was actually adopted.
Weight. Fully resolved by house rule 2 above. No reference wins this one.
