takeones-ui

Takeone's UI

Taste is a process, not a mood:

truth → mode → direction → DESIGN.md → structure → hierarchy → detail → verify.

Clarity is separate from taste. When the job is "a stranger must be able to use this without being taught" — onboarding, forms, settings, checkout, anything the user cannot be trained on — read FOOL.md first. That file owns usability; this one owns quality.

Run it every time you build, restyle, or review an interface. The outcome must look deliberately designed: clear hierarchy, confident restraint, consistent systems, complete states.

Operating principles

1. The brief wins. Pinned aesthetics, brand rules, reference screens, and user constraints override your taste. Redirecting a clear brief toward a generic "clean" look is failure.
2. Reference before pixels. A supplied screenshot, brand, SVG, or existing screen is law. Replicate its hierarchy, spacing rhythm, color temperature, radii, and density first. Add nothing until the replica is faithful.
3. One direction, one mode, fully executed. Never blend presets, and never apply marketing ambition to an operating screen.
4. Refinement preserves; redesign replaces. A refinement keeps identity, behavior, copy, and everything outside scope. A redesign keeps product truth but treats the old look as an anti-reference — do not split the difference into polish on a discarded look.
5. Restraint. Every border, gradient, shadow, icon, and card must earn its place. When in doubt, remove it. Whitespace is a feature, not leftover space.
6. Hierarchy is contrast — size, weight, color, space — not decoration. One primary action per view.
7. Tokens are the contract. Color, spacing, radius, type, shadow, and motion come from a token set recorded in DESIGN.md and implemented once. No stray 13px, #888, or margin: 7px.
8. States and browser surfaces make it real. Hover, focus-visible, active, disabled, loading, empty, error, selected — plus selection color, caret, scrollbars, and focus rings.
9. Verify with eyes, then fix in a batch. Screenshot at shipping sizes, inspect computed styles, walk the keyboard path. One rendered look, all checks, one batch of fixes.
10. Impact is a detail, not a layer. High-tech comes from precision, type, and one signature moment, not stacked effects. Set an impact level per surface and keep the usability floor.

Choose the path

Request	Do
Build a new screen or app	Full workflow, steps 0–11.
Make an existing UI better	Step 0, audit with references/review-checklist.md, preserve identity, fix P0/P1 first.
Redesign / replace the look	Step 0, choose a new direction, replace the visual world and update DESIGN.md.
Audit or critique only	Review checklist and report; do not edit unless asked.
Color, type, or token work only	scripts/palette.mjs + references/color-and-type.md; update DESIGN.md.
One component	Seven-line brief + component spec; skip full DESIGN.md.
Make it look high-tech or more expressive	Set an impact level; read references/high-tech-expression.md; keep the floor.
A sequence of beats that must hold together (launch, onboarding, tour)	Read references/continuity-and-rhythm.md; beat sheet with carries; score the boundaries.
Desktop port of a web UI	Platform-fit rules + density changes; reuse the token roles.
A first-time user must be able to use it unaided (forms, checkout, settings, onboarding, any untrained audience)	Read FOOL.md: one job per screen, labels that name outcomes, visible state, the stranger test. Then proceed with steps 3–11.

0. Locate the truth

Before designing anything:

1. Read DESIGN.md if it exists; it is the visual contract. Also read AGENTS.md, token files, global CSS, and existing components.
2. Look at the current UI at the sizes it ships at. Visual authority is evidence, not a filename: a missing DESIGN.md does not make a project greenfield.
3. If a reference screenshot conflicts with the code, the screenshot wins for appearance; the code wins for behavior. Ask only if the conflict changes scope.
4. Decide: refine (keep the world) or redesign (replace it). State which one in one line.

1. Frame the job

Choose the mode from the surface, not the product. A tool's landing page is Persuade; a fashion house's docs are Read.

Mode	Visitor success	Surfaces	Ambition
Persuade	decides and acts	landing, marketing, pricing, campaign	High: distinctive, committed, memorable.
Operate	completes a task	app, dashboard, editor, admin, settings	Precision and restraint; familiar patterns; speed over expression.
Read	understands something	docs, articles, help, changelog	Structure for comprehension; comfortable measure; calm hierarchy.
Experience	is inside the work	portfolio, gallery, showcase	The artifact leads; the interface recedes; craft over chrome.

Then set three dials (1–5) and record them:

• Expression — 1 (quiet) to 5 (expressive).
• Density — 1 (airy) to 5 (compact).
• Motion — 1 (still) to 5 (cinematic).

Defaults: Persuade 4/2/3, Operate 2/3/1, Read 2/2/1, Experience 5/2/4. Adjust to the brief, not to habit.

Then pick an impact level for this surface and record it in the brief:

Level	Surfaces	Expression
0 Quiet	settings, tables, forms, checkout, destructive flows	No signature. Precision, states, and type only.
1 Refined	default product UI	One accent, hairlines, subtle depth, micro-detail.
2 Signature	marketing shell, auth, onboarding, empty/success/404, command palette, about	One signature moment plus one supporting detail.
3 Showcase	portfolio, launch, event, experimental showcase	One world, one concept, one moment; the floor still applies.

The level is per surface, not per product: a landing page can be level 2 while its settings remain level 0. Full rules: references/high-tech-expression.md.

Ask at most three questions, only if unanswered: (a) audience and primary goal, (b) platform and target window sizes, (c) reference images / brand assets / existing design system. Otherwise decide, state the assumption in one line, and proceed. Never stall.

2. Write or refresh DESIGN.md

DESIGN.md is a plain-markdown design contract that agents read to keep UI consistent. AGENTS.md says how to build; DESIGN.md says how it looks.

• Multi-screen work or a new visual world: copy assets/DESIGN.template.md to the project root as DESIGN.md and fill it before coding.
• One-off component or micro-task: write the seven-line brief below instead; promote it to DESIGN.md if a second screen appears.
• Existing project: update DESIGN.md in the same change that alters tokens or visual rules.

Direction:   <one line, e.g. "quiet minimal, light, single blue accent">
Mode/dials:  Persuade|Operate|Read|Experience + Expression/Density/Motion
Impact:      0 quiet | 1 refined | 2 signature | 3 showcase
Reference:   <screens/products + what to borrow from each>
Palette:     bg / surface / text / muted / border / accent + hover
Type:        family + scale + two weights
Shape:       radius scale, border treatment, shadow level
Density:     control heights, row height, section spacing
Asset rule:  <own photos / brand icons / data source>
Signature:   <the one moment this surface is remembered by, or none>

3. Choose direction

• Reference provided: derive the direction from it. This beats any preset.
• No reference: choose exactly one preset from references/style-directions.md. Do not invent a hybrid.
• Impact 2–3: commit to one visual idea and one signature moment (a composition, typographic device, image treatment, or motion moment). "Clean and modern" is not an idea.
• Impact 0–1: ban decorative flourishes; earn quality through alignment, density, and precise states. The expression dial can be high, but spectacle is not allowed.
• High-tech without noise: precision, hairlines, mono metadata, one electric accent, one dark technical surface, real UI as imagery. Never neon/HUD defaults.

4. Set tokens and assets

• Start from assets/tokens.css; adjust hue, radius, and density to the brief, then record the final values in DESIGN.md.
• Define semantic roles, not color names: canvas, surface, text, text-muted, border, accent, on-accent, focus, danger.
• Components may only use tokens. Raw values allowed solely for 0, 1px, 100%, and one-off optical corrections with a comment.
• Build light and dark together. Dark mode is not an inversion; see references/color-and-type.md.
• Asset sourcing order: the project's own assets → user-supplied → generated → openly licensed photos/icons (CC0, public domain, CC BY) → code-drawn → typography and color alone. Never hotlink; credit open assets with title, creator, and source. Never invent product data, street addresses, testimonials, or metrics in app screens.

5. Plan structure, then build it

• Before markup, list the sections/screens in order and each one's single job. One idea per section. If a section has three jobs, split it.
• Build the skeleton with real content: landmarks, heading order, labeled controls; for desktop, native window chrome, menus, shortcuts.
• Web: nav / main / aside / footer; app shell: sidebar + topbar + content; grid and breakpoints. Keep equal left and right content edges on marketing pages.
• Design mobile and desktop together. Decide the reflow before polishing either.
• If the skeleton does not read without color, the layout is wrong — fix that before decoration.

6. Add hierarchy and detail

Layer	Rules
Typography	Body 15–17px web, 13–14px desktop; line-height 1.5–1.7; measure 65–75ch; max 4 visible sizes and 3 weights per screen; display max 6rem; tracking floor −0.04em; balance headings.
Space	4px base: 4/8/12/16/24/32/48/64/96/128. Gaps must differ by ≥2× between grouping levels. More space above a heading than below it. Section padding 64–128px desktop, 40–64px mobile.
Color	One accent, reserved for primary action, links, selection, focus, and one data series. Neutrals tinted 2–6% toward the brand hue. On colored surfaces, tint secondary text from that hue — never gray.
Surfaces	Max two elevation levels above the page. Choose one separation strategy — tonal surfaces, hairline borders, or shadows — and use it consistently. Shadows carry an offset and a soft blur.
Shape	One radius scale; nested radii must step down (child = parent − padding). Round only what reads better round.
Components	Complete the state matrix before shipping: default, hover, active, focus-visible, disabled, loading, error, selected, empty.
Copy	Sentence case. Verb-first buttons ("Save changes", not "Submit"). Errors say what happened and how to fix it. Empty states say what goes here and offer the next action.

One signature moment. At impact 2–3, plan one signature moment plus at most one supporting detail — not the same fade-up on every section. At impact 0–1, motion is feedback only; coolness lives in micro-detail: focus rings, cursor, tabular numerals, keycaps, menu transitions.

Sequence, not slides. If the moment spans several beats, each boundary must carry something visible into the next; shot lengths vary ≥4×; one camera holds it. A sequence whose beats replace each other scores 0.00 however good each beat is. See references/continuity-and-rhythm.md.

High-tech without noise. Precision, hairlines, mono metadata, one electric accent, one dark technical surface, and real UI as imagery. No neon/HUD, scanlines, particle fields, fake terminals, or effect stacks. See references/high-tech-expression.md.

Icons. Never emoji or Unicode glyphs. Use one open-license SVG family — Lucide (ISC), Phosphor/Tabler/Heroicons (MIT), or Material Symbols (Apache-2.0) — or authored SVGs; self-host, record the license, use currentColor, one stroke width, sizes 16/20/24.

7. Non-negotiables

1. Exactly one primary button per view; secondary actions are quieter by fill, not by size.
2. Text contrast: 4.5:1 for body, 3:1 for ≥24px or ≥18.66px bold, 3:1 for icons, meaningful borders, and focus indicators.
3. Spacing and sizes come from the scale. No arbitrary values.
4. Max two font families, three weights, four visible sizes per screen.
5. One accent color. Semantic colors (success, warning, danger) never double as accents.
6. Focus is always visible (:focus-visible ring, 2px + offset), never outline: none without a replacement.
7. Every interactive element has hover, active, focus-visible, disabled; every async area has loading, empty, error.
8. Touch targets ≥44×44px; pointer targets never below 24×24px (WCAG 2.2 minimum).
9. Motion uses transform/opacity (plus blur/mask/clip when smooth), 120–300ms for UI, and honors prefers-reduced-motion.
10. No horizontal scroll at 320px; no clipped text; no overlapping content at any width.
11. One UI language, one open-license SVG icon family (Lucide, Phosphor, Tabler, Heroicons) or authored SVGs, self-hosted, one stroke width, sizes 16/20/24. Never emoji.
12. Destructive actions look destructive and require confirmation or provide undo.
13. Dialogs trap focus, close on Escape, and return focus to the trigger.
14. No full-screen spinners for partial updates; use skeletons or inline progress.
15. Theme the browser surfaces: selection, caret, scrollbars, focus rings, underline offset, tabular numerals.
16. Never claim visual quality you have not verified with a screenshot and computed styles.

8. Hard bans

These read as machine-assembled unless the committed world explicitly earns them. When in doubt, rewrite, do not soften.

• Eyebrow/kicker labels above headings as decoration. A small label needs a functional reason (status, category, version).
• Nested cards. A card inside a card is always wrong.
• Same-size icon + heading + text card grids used as the page structure.
• The hero-metric template — big number, small label, supporting stats, accent — used as decoration rather than real data.
• Gradient text for emphasis. Emphasis comes from weight or size.
• Effect stacks. More than one signature moment, or more than one decorative material/filter family, on the same surface.
• Generic HUD/cyberpunk effects. Neon rings, scanlines, glitch, random hex, fake terminals, or floating 3D orbs used as a stand-in for an idea.
• Decorative glass/blur. Allowed only when translucency is the committed world and contrast passes against the worst-case backdrop.
• Hard offset shadows (4px 4px 0) outside an actual neobrutalist world.
• Colored side borders above 1px on cards, callouts, or alerts. Use a tinted surface or an icon.
• Section numbers 01/02/03 unless the sequence carries information the user needs.
• Sparklines, progress rings, or generic soft-shadowed rounded rectangles standing in for content.
• Monospace as a costume for "technical". Use it for code, data, and measurement.
• Emoji or Unicode glyphs as an icon system. Never use emoji in UI. Use one open-license SVG set (ISC/MIT/Apache-2.0) or authored SVGs; self-host, record the license, and keep stroke width and sizes consistent.
• A system display face (Impact, Arial Black, the platform UI font) as the brand voice on a marketing/experience page. Source a face that matches the world.
• Light/dark chosen by category. Choose from the use scene: who, where, under what ambient light.

9. Common failure modes

• Every section is a rounded card floating on #f5f5f5 with the same 16px shadow.
• Centered hero + three feature cards + gradient blob + colored icon squares.
• Everything has equal visual weight; the eye has nowhere to land.
• Eight font sizes, six radii, five shadows, three accent colors.
• Pure black text on pure white with #999 secondary text.
• 12px body text and 8px padding to "fit more"; center-aligned paragraphs longer than two lines.
• Untouched shadcn/MUI/Bootstrap demo styling; placeholder copy; mixed Chinese/English UI text.
• Animating everything, including layout properties; ignoring reduced motion.
• A modal for a trivial confirmation; toasts for critical errors; hover-only affordances; clickable <div>s.
• Dark mode by inversion: pure black, pure white text, over-saturated accent.
• Forms that use placeholders as labels; errors far from the field; disabled controls with no explanation.
• Invented testimonials, metrics, stock-photo collages, or fake product dashboards on a real page.

10. Platform fit

Web marketing — larger type is allowed (display 36–72px), one accent, real imagery or none, generous section rhythm, one authored moment. Avoid stock-photo collages and feature-card grids as the default.

Web app — density and speed win. Keyboard-first, command palette for power users, persistent navigation, tables with clear alignment, optimistic updates.

Desktop (Qt/QML, Win32/WPF, macOS) — follow OS conventions before aesthetics: native window chrome, menus, shortcuts, context menus, system accent/theme, high-DPI. Body text 13–14px; control heights 28–36px; table rows 32–40px; no web-style 60px hero. Respect system dark mode and reduced motion. In Qt, QSS supports only a CSS subset (no shadows/transitions) — use QML effects or a theme singleton; see references/layout-and-components.md#desktop.

11. Verification protocol

Use a real browser (browser-use MCP, Playwright, Chrome DevTools). Serve over HTTP when the app uses modules or fetch; a static file is fine otherwise. Run all checks in one pass, fix every FAIL in one batch, and re-render. Three rounds maximum; then report what remains.

1. Open at 1440×900 and screenshot the full page. Then 1024, 768, and 390 (add 320 if time allows).
2. Composition: hero headline fits in 2–3 lines at 1440; H1 readable in ~1.2s; left and right content edges equal; no blank gap taller than half a screen; no off-center drift; no horizontal scroll.
3. Type: max two families; body full-ink (not #999); computed sizes and line-heights match tokens; headings balanced; no clipped text at any breakpoint.
4. Color: run node scripts/contrast.mjs on the core pairs (text/canvas, muted/canvas, on-accent/accent, border/surface, focus/canvas). Fix failures. Toggle dark mode and re-screenshot.
5. States: hover, active, focus-visible, disabled, loading, empty, error on every component that can have them. Tab through the whole screen; dialogs trap and restore focus.
6. Motion and expression: one signature moment at the declared impact level; none on high-frequency task paths; no effect stacks or HUD/neon defaults; enable reduced motion and confirm nothing is hidden or unusable. At impact 0–1, expression is micro-detail only. If the moment is a sequence, check every boundary for carry, confirm shot lengths vary ≥4×, and confirm a rest exists.
7. Assets and copy: real images loaded and credited; no placeholder text, invented data, mixed languages, or emoji icons; SVG icons are one licensed family, self-hosted, with the license recorded.
8. Browser surfaces: selection, caret, scrollbars, focus rings, tabular numerals — themed, not default where the design would notice.
9. Console: no errors, failed requests, or layout-shift warnings.
10. Compare the reference and your screenshot side by side; list the three biggest differences; fix them.
11. Report what you verified (widths, themes, contrast, keyboard) and what you did not.

Definition of done

• Mode and dials chosen; DESIGN.md written or updated; one direction, no blending.
• Tokens cover color, type, space, radius, shadow, motion; no raw values in components.
• Hierarchy reads at first glance; one primary action; impact level declared; at most one signature moment.
• High-tech cues are precise, not noisy; no HUD/neon/particle defaults; the expression layer is removable without reducing usability.
• Light and dark both pass contrast; focus visible everywhere.
• All states implemented: hover, active, focus, disabled, loading, empty, error.
• Responsive at 1440/1024/768/390 with no overflow or clipping.
• Keyboard path complete; dialogs behave; reduced motion honored.
• Any multi-beat sequence carries at every boundary, varies shot length ≥4×, and has a rest.
• Real copy and assets, one language, consistent terminology and icons.
• Browser surfaces themed; console clean.
• Screenshot verified against the reference or the chosen preset.

Resources

File	Read when
FOOL.md	Making a screen obvious rather than merely good: the four rules, wording, state, affordance, the six stranger tests, the usability floor.
references/design-principles.md	Layout, hierarchy, spacing, type, color, density, feedback fundamentals.
references/color-and-type.md	Building palettes and type systems, light/dark mapping, contrast rules, font stacks.
references/layout-and-components.md	Page archetypes, component specs, state matrix, responsive rules, desktop/Qt specifics.
references/motion-and-interaction.md	Durations, easing, choreography, micro-interactions, reduced motion.
references/continuity-and-rhythm.md	Making a sequence on a single take: carry, one camera, rhythm ≥4×, carry scoring.
references/high-tech-expression.md	Impact ladder, high-tech cues, signature moment menu, expression audit.
references/style-directions.md	Choosing a direction; seven presets with exact palettes and type.
references/review-checklist.md	Auditing an existing UI; P0–P3 review format; WCAG 2.2 AA and craft-floor checks.
references/inspiration.md	Study list of design systems, products, and the sources that shaped this skill.
scripts/contrast.mjs	Checking WCAG contrast of token pairs, with suggested passing variants.
scripts/palette.mjs	Generating an accent and neutral ramp from one seed color (OKLCH, gamut-clamped).
assets/DESIGN.template.md	Starting a DESIGN.md for a project; tokens plus visual rules.
assets/tokens.css	Starter token set; copy into the project and adjust hue/radius/density.
examples/motion/one-take.html	Learning what carry looks like; open it, then read the beat sheet in the source.