From a8deb6af6a14bc5e56e86289a2858a0258558388 Mon Sep 17 00:00:00 2001 From: Craig Jennings Date: Sun, 19 Apr 2026 15:57:50 -0500 Subject: feat: adopt frontend-design (Apache 2.0 fork) + progressive-disclosure extensions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Forked verbatim from anthropics/skills/skills/frontend-design (Apache 2.0). LICENSE.txt preserved. Upstream SKILL.md prose (aesthetic guidance, archetype list, anti-pattern callouts) kept intact. Extensions added (clearly marked, load progressively — base SKILL.md stays lean for simple cases): SKILL.md: - Description extended with explicit negative triggers: narrow maintenance (single CSS bug, dependency upgrade, a11y-only retrofit), operational contexts where stakeholder has specified "minimal, functional, no creative direction," backend / API work, non-web UIs (mobile native, desktop, terminal), and refactoring without visible design component. - New "Workflow" section at the end of SKILL.md: four phases (intake, commitment, build, review) with pointers to reference files. Simple component tweaks skip the workflow; non-trivial redesigns walk it. - New "References" section: table mapping file → load-when condition. - Attribution footer marking upstream source + what's locally added. references/workflow.md (~150 lines) Intake questions (purpose, audience, operational context, functional priority, technical constraints, brand references, success criteria). Commitment step (archetype pick, trade-offs, font pairing, palette, motion, layout as one-line decisions). Build reminders. Review pointer. Guidance on when to skip phases. references/accessibility.md (~200 lines) WCAG AA contrast thresholds + practical check guidance. Keyboard navigation + focus management. Semantic HTML + ARIA rules. Reduced- motion CSS snippet. Smoke checklist. Operational-context note for defense / ISR work. references/responsive.md (~160 lines) Mobile-first vs desktop-first decision. Named breakpoints (Tailwind- style) vs magic pixels. Container queries. Aesthetic translation table — how each archetype handles small-screen scaling. Responsive typography with clamp(). Operational-dashboard note: desktop-primary is a legitimate product decision. references/design-review.md (~170 lines) Archetype check (does the build read as what was committed to?). Anti-pattern grep for fonts, palette, layout, motion, backgrounds, components. Code-quality-match check (ornate design + lazy code = failure). Performance sanity. Convergence check (if last 3 builds all used the same archetype, break the pattern). The one-sentence test for memorability. references/rationale-template.md (~160 lines) Template for design-rationale.md alongside the build. Nine sections (purpose, archetype, locked decisions, deliberately absent, accessibility, responsive, implementation, open questions, references). Filled example using a DeepSat SOCOM demo landing page to show density and specificity. Structure matches Anthropic's own pdf / docx / webapp-testing pattern (SKILL.md entry + references/ for progressive disclosure). Makefile SKILLS extended; make install symlinks globally. Adoption caveat resolved: name kept as `frontend-design` (not renamed to ui-design) — "frontend" signals scope (web code, not mobile / desktop / terminal UIs), upstream parity preserved for attribution. --- frontend-design/references/workflow.md | 86 ++++++++++++++++++++++++++++++++++ 1 file changed, 86 insertions(+) create mode 100644 frontend-design/references/workflow.md (limited to 'frontend-design/references/workflow.md') diff --git a/frontend-design/references/workflow.md b/frontend-design/references/workflow.md new file mode 100644 index 0000000..bd0f3a5 --- /dev/null +++ b/frontend-design/references/workflow.md @@ -0,0 +1,86 @@ +# Workflow + +Four phases for non-trivial frontend work. Cheap to skip individual phases when context warrants, but don't short-circuit the chain by default. + +## Phase 1 — Intake + +Before coding, understand what's being built and for whom. Ask these, one at a time, multiple-choice where possible. Don't batch. + +**Purpose** +- What is this interface for? (landing page / dashboard / component / marketing site / internal tool / client demo / design exploration / other) +- What problem does it solve? One sentence. + +**Audience** +- Who uses this? (general public / executives / technical users / operators / customers / internal team) +- What's their expected device / context? (desk on a big screen / mobile on the move / constrained environment) + +**Operational context** +- Consumer-facing or operational? (consumer → aesthetic distinctiveness helps; operational → readability + scannability matter more) +- Is there a design system to respect, or is this greenfield? +- Any brand guidelines or existing visual language to match / deliberately depart from? + +**Functional priority** +- Density vs scannability vs delight — which wins when they conflict? +- Read-only, interactive, or input-heavy? + +**Technical constraints** +- Framework / stack (React / Next / Vue / Svelte / vanilla HTML+CSS / static site / other) +- Existing design system (Tailwind / shadcn / custom / none) +- Performance budget (if any) +- Accessibility target (WCAG AA is default; AAA for some contexts) +- Browser support (modern-only OK, or need IE11-style fallbacks?) + +**References** +- Any moodboard links, screenshots, sites you like / dislike? +- Brand color palette, logos, fonts already in use? + +**Success criteria** +- What does "good" look like for this? One-sentence test ("looks professional but not corporate" / "feels like a game" / "hides complexity behind calm surfaces" / etc.) +- How will we know when to stop iterating? + +Stop asking when you can state the goal back in one sentence and the user confirms. + +## Phase 2 — Commitment + +Before writing code, lock the aesthetic direction explicitly. State all of these out loud (in output) so the user can push back before time is spent: + +- **Archetype chosen.** One of: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, or a named variant. +- **Why this archetype fits** the purpose and audience from Phase 1. +- **What's being traded away.** (Maximalism trades subtlety; minimalism trades information density; playful trades gravitas; etc.) +- **Font pairing**, one line. Display + body, both named. Not Inter, Roboto, Arial, or system defaults unless specifically justified. +- **Palette**, one line. 2-3 dominant colors + 1-2 sharp accents. Not "purple gradient on white." +- **Motion philosophy**, one line. ("Staggered page-load reveal, subtle hover states, no scroll-jacking" or "no motion — stillness and typography do the work" or "aggressive hover interactions — this is supposed to feel alive.") +- **Layout approach**, one line. (Asymmetric grid / classic 12-col / brutalist stack / magazine spreads / whatever fits the archetype.) + +**If the user pushes back**, revise before building. Cheaper to pivot now than after implementation. + +## Phase 3 — Build + +With the commitment locked, implement. The aesthetic guidance in `../SKILL.md` is the main reference for taste decisions. + +**Layout-significant work?** Load [responsive.md](responsive.md) and plan the breakpoint strategy *before* committing to a primary viewport layout. + +**Interactive components (forms, dialogs, menus, complex controls)?** Load [accessibility.md](accessibility.md) and apply the discipline during build, not as a retrofit. + +**Match implementation complexity to aesthetic vision.** Maximalism needs elaborate code (layered animations, custom cursors, grain overlays, scroll effects). Minimalism needs precision (impeccable spacing, considered typography scale, restraint in color). Don't build the wrong kind of effort. + +## Phase 4 — Review + +Before handoff, self-audit. Load [design-review.md](design-review.md) and walk the checklist: + +- Did the build hit the chosen archetype? +- Any AI-slop defaults slip back in? (Inter, purple-on-white, predictable card layouts, etc.) +- Accessibility smoke check (contrast, keyboard, focus, reduced-motion) +- Responsive smoke check (does the aesthetic translate to mobile?) +- Does the code quality match the aesthetic? (Lazy code under ornate design is a failure.) + +Emit a `design-rationale.md` using [rationale-template.md](rationale-template.md) so the next iteration or the next engineer has context for the choices made. + +## When to skip phases + +- **One-line style tweak** ("change the heading color to match the brand"): skip phases 1, 2, 4. Just apply the change. +- **Refactoring existing code without design changes**: not this skill — use the general refactor skill. +- **Bug fix in existing design**: skip phase 1 (context is already there) and phase 2 (don't pivot the archetype for a bug fix). Build and review. +- **Complete rebuild / new design**: don't skip any phase. + +The discipline is there to prevent bad decisions at speed. Skipping for genuinely trivial work is fine; skipping because "it's faster" on non-trivial work is how AI slop wins. -- cgit v1.2.3