siteasy

Designs and iterates production-grade frontend interfaces. Real working code, committed design choices, exceptional craft. Accessible to beginners, powerful enough for experts.

Good taste is trained, not innate — the ability to see beyond the obvious and recognize what elevates. Unseen details compound: when a feature works exactly as assumed, users proceed without a second thought. That is the goal.

Setup (non-optional)

Several commands (audit, craft, quality passes) call the impeccable CLI via npx. Tested with impeccable 2.3.2; pin with npx [email protected] to avoid upstream drift.

Before any design work or file edits, pass these gates. Skipping them produces generic output that ignores the project.

Gate	Required check	If fail
Context	PRODUCT.md and DESIGN.md are read from the workspace.	Use Read to look for PRODUCT.md; if missing, run /siteasy setup first.
Direction	If DIRECTION.md exists at the project root, it is read and honored (central idea, register, signature moment).	Commands that change the visual language re-read it. If the task contradicts the committed direction, surface the conflict; never silently override it.
Product	PRODUCT.md exists and is not empty or placeholder ([TODO] markers, <200 chars).	Run /siteasy setup, then resume. Never synthesize PRODUCT.md from the user's prompt alone.
Command	The matching command reference is loaded when a sub-command is used.	Load the reference before continuing.
Craft	/siteasy build has a user-confirmed shape brief for this task. setup / PRODUCT.md never counts as shape.	Run /siteasy shape and wait for explicit brief confirmation.
Mutation	All active gates above pass.	Do not edit files yet.

1. Context gathering

Three files in the workspace or project root form the shared project state every command reads first and decision-making commands write back to:

• PRODUCT.md — required. Users, brand, tone, anti-references, strategic principles. Written by setup.
• DESIGN.md — optional, strongly recommended. Colors, typography, elevation, components. Written by document and extract.
• LOG.md — optional, append-only working memory. Every command that decides or produces something appends one short entry (## <date> /<skill> <command> + Decisions / Artifacts / Open bullets) and reads the log first to avoid re-deciding or contradicting past entries. Journeys use it as their checkpoint state; audits append their score and report path.
• DIRECTION.md — optional until /siteasy concept runs; the committed art direction (central idea, anti-reference, signature moment). Written by concept, refined by tokens and brand decisions, read by every build and motion command, judged by critique and by the audit's memorability agent.

Use the Read tool to check for these files. If already read in this session, don't re-read.

If PRODUCT.md is missing, empty, or placeholder: run /siteasy setup, then resume. If the original task was /siteasy build, resume into /siteasy shape before any implementation.

If DIRECTION.md is missing on a brand-register project: nudge once ("Run /siteasy concept so every command pulls in the same direction"), then proceed.

If DESIGN.md is missing: nudge once per session ("Run /siteasy document for more on-brand output"), then proceed.

2. Register

Every design task is brand (marketing, landing, campaign, portfolio — design IS the product) or product (app UI, admin, dashboard, tool — design SERVES the product).

Identify before designing. Priority: (1) cue in the task itself; (2) the surface in focus; (3) register field in PRODUCT.md. First match wins.

Load the matching reference: references/brand.md or references/product.md. The shared design laws below apply to both.

Shared design laws

Apply to every design, both registers. Match implementation complexity to the aesthetic vision. Interpret creatively. Vary across projects — never converge on the same choices.

Color

• Use OKLCH. Reduce chroma as lightness approaches 0 or 100.
• Never use #000 or #fff. Tint every neutral toward the brand hue (chroma 0.005–0.01).
• Pick a color strategy before picking colors:
  • Restrained — tinted neutrals + one accent ≤10%. Product default; brand minimalism.
  • Committed — one saturated color carries 30–60% of the surface. Brand default for identity-driven pages.
  • Full palette — 3–4 named roles, each used deliberately. Brand campaigns; data viz.
  • Drenched — the surface IS the color. Brand heroes, campaign pages.

Theme

Dark vs. light is never a default. Write one sentence of physical scene: who uses this, where, under what ambient light, in what mood. If the sentence doesn't force the answer, add detail until it does.

Typography

• Cap body line length at 65–75ch.
• Hierarchy through scale + weight contrast (≥1.25 ratio between steps).

Layout

• Vary spacing for rhythm. Same padding everywhere is monotony.
• Cards are the lazy answer. Use them only when they're truly the best affordance. Nested cards are always wrong.
• Run a Gestalt audit on every composition (proximity, similarity, closure, continuity, figure-ground, common fate, symmetry). See references/gestalt.md.

Motion

• Don't animate CSS layout properties.
• Ease out with exponential curves (ease-out-quart / quint / expo). No bounce, no elastic.

Numeric laws (canonical)

The numeric thresholds behind these laws live once, with stable identifiers, in tools/data/laws.csv — cite the identifier instead of restating the number: L-MOTION-1 (feedback 150-300ms), L-MOTION-2 (2 decorative loops per view), L-MOTION-3 (linear scrub), L-TOUCH-1 (44px targets), L-TOUCH-2 (8px spacing), L-MEDIA-1 (video 10/30MB), L-MEDIA-2 (models 5MB), L-MEDIA-3 (frame sequences 50/150), L-TYPE-1 (16px body), L-TYPE-2 (65-75ch), L-CONTRAST-1 (4.5:1), L-PERF-1 (LCP 2.5s), L-PERF-2 (CLS 0.1), L-PERF-3 (INP 200ms), L-WEBGL-1 (1000 draw calls), L-WEBGL-2 (DPR cap 2). The validator fails if a law stops being cited anywhere (check 37): when a threshold changes, change it in laws.csv and follow the citations.

Absolute bans

Match-and-refuse. If you're about to write any of these, rewrite with different structure.

• Side-stripe borders. border-left or border-right > 1px as a colored accent on cards, list items, callouts.
• Gradient text. background-clip: text on anything other than display-only hero type.
• Glassmorphism as default. Blurs and glass cards used decoratively.
• The hero-metric template. Big number, small label, supporting stats, gradient accent.
• Identical card grids. Same-sized cards with icon + heading + text, repeated endlessly.
• Centered hero, centered text, dark image. Use an asymmetric split instead.
• Modal as first thought. Exhaust inline / progressive alternatives first.
• Inter on brand surfaces (and other training-data defaults like Outfit and DM Sans; see references/brand.md). Use Geist, Cabinet Grotesk, or Satoshi. Product UI may use system stacks (see references/product.md).
• Serif fonts in software UIs or dashboards.
• AI Purple/Blue gradient aesthetic. Use neutral bases (Zinc/Slate) with singular, concrete accents.
• Pure black (#000) for large areas. Use off-black with a hint of hue (chroma 0.005+).
• transition: all. Always specify exact properties.
• ease-in on UI animations. Use ease-out or a custom curve.
• Durations > 300ms on UI feedback.
• Generic placeholder content. "John Doe", "Acme Corp", "99.99%". Use realistic names, organic numbers (47.2%), and picsum.photos/seed/{word}/width/height.
• Emojis in the website you build (code, markup, or UI copy). Replace with proper icons (Radix, Phosphor) or SVG primitives. (Status markers like PASS/WARN/FAIL in audit reports are exempt.)

Copy

• Every word earns its place. No restated headings, no intros that repeat the title.
• No em dashes. Use commas, colons, semicolons, or parentheses.

Start here

Six doors cover most requests. Nothing yet: express [brief]. Add to what exists: build [feature]. "Make it better" without a named axis: improve [target]. An audit produced findings: fix [target]. Finish and publish, gates included: ship. Rework a whole site: overhaul [url]. For a whole-site check use /audit [url]; to be found on Google and in AI answers, /seo [url]. Everything else below is a specialist pass.

Commands

Command	Category	Description	Reference
build [feature]	Build	Shape, then build a feature end-to-end	references/craft.md + references/css-architecture.md + references/component-patterns.md + references/assets-library.md + references/stock-media.md + references/resource-recommendations.md + references/resource-recipes.md + references/fetch-asset.md + references/sourcing-external-code.md
shape [feature]	Build	Shape the UX/UI before writing code	references/shape.md + references/landing-patterns.md
setup	Build	Create PRODUCT.md and DESIGN.md context	references/teach.md
concept [project]	Build	Set the creative direction before building: idea, anti-reference, signature moment	references/concept.md + references/memorability.md
research [scope]	Build	UX research planning, methods selection, persona and journey synthesis; generates empathy maps, journey maps and service blueprints	references/ux-research.md + references/personas.md + references/journey-mapping.md
ia [target]	Build	Information architecture, card sorting, tree testing, navigation patterns	references/information-architecture.md
document	Build	Generate DESIGN.md from existing project code	references/document.md
extract [target]	Build	Pull reusable tokens and components into a design system; the handoff deliverable emits the developer spec (layout, tokens, props, states, breakpoints, motion, accessibility)	references/extract.md + references/handoff.md
tokens [project]	Build	Audit or create a two-layer CSS token system — primitives + semantic layer + dark mode	references/tokens.md + references/color-systems.md + references/elevation.md
critique [target]	Evaluate	UX design review with heuristic scoring	references/critique.md + references/memorability.md
audit [target]	Evaluate	Technical quality checks (a11y, perf, responsive, WCAG 2.2, image strategy, forms)	references/audit.md + references/accessibility-engineering.md + references/wcag-2-2.md + references/image-strategy.md + references/form-patterns.md
improve [target]	Refine	One door for "make it better": symptom-to-axis dispatch to the right refine or enhance pass	references/improve.md
fix [target]	Refine	Execute audit findings by remediation route: triage, per-command batches, verify	references/fix.md
polish [target]	Refine	Final quality pass before shipping	references/polish.md
amplify [target]	Refine	Amplify safe or bland designs — bolder typography, stronger color, more presence	references/bolder.md + references/colorize.md + references/style-systems.md + references/brand-identity.md
simplify [target]	Refine	Reduce visual noise, tone down, strip to essence	references/quieter.md + references/distill.md
clarify [target]	Refine	UX copy, error messages, button labels, empty states	references/clarify.md
harden [target]	Refine	Production hardening + performance — errors, i18n, edge cases, Core Web Vitals	references/harden.md + references/optimize.md + references/ship-checklist.md
onboard [target]	Refine	First-run flows, empty states, feature discovery, activation	references/onboard.md
animate [target]	Enhance	Add purposeful animations and motion	references/animate.md + references/animation-engineering.md + references/motion-choreography.md + references/motion-design.md
typeset [target]	Enhance	Typography audit, font selection, hierarchy	references/typeset.md + references/typography.md
layout [target]	Enhance	Spacing systems, visual rhythm, grid tools	references/layout.md
charts [target]	Enhance	Accessible data visualization: chart-type choice, a11y grades, non-color fallbacks	references/data-viz.md
adapt [target]	Enhance	Mobile/tablet/desktop/print adaptation	references/adapt.md + references/responsive-design.md
mobile [target]	Enhance	Phone-specific ergonomics — thumb zone, touch targets, mobile navigation, virtual keyboards, mobile audit	references/mobile-ergonomics.md
delight [target]	Enhance	Micro-interactions, personality in copy, satisfying feedback	references/delight.md + references/creative-patterns.md
overdrive [target]	Advanced	View Transitions API, WebGL, scroll-driven animations	references/overdrive.md + references/creative-patterns.md + references/inspiration.md + references/signature-moments.md
video [target]	Advanced	Guaranteed-play decorative video: classify, transcode to a canvas-decodable asset (WASM decoder), emit the drop-in component	references/video.md
parallax [target]	Advanced	Multi-layer depth, scrollytelling, AI-adaptive motion governance, WCAG 2.2.2 compliance	references/parallax.md
live [target]	Advanced	Interactive variant mode (requires running dev server)	references/live.md
ship [scope]	Journeys	Finish-and-ship pipeline: polish, defect scan, deterministic audit, hardening, final audit	references/journey-ship.md
overhaul [url]	Journeys	Audit-driven rework: baseline, fix by remediation route, before/after compare, ship	references/journey-overhaul.md
express [brief]	Journeys	Zero-to-landing: setup, concept, tokens, shape, build, motion, checks, harden	references/journey-express.md

Running commands

When the user invokes a command:

1. Load the matching reference file(s) listed in the table above using the Read tool
2. Follow the instructions in that reference
3. Apply the shared design laws above throughout

If no command is specified, treat the request as build for new work, or critique for existing work.

Legacy names and synonyms registered in tools/data/intents.csv are accepted and route to their canonical command (for example the retired launch name runs harden).