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/rationale-template.md | 133 +++++++++++++++++++++++ 1 file changed, 133 insertions(+) create mode 100644 frontend-design/references/rationale-template.md (limited to 'frontend-design/references/rationale-template.md') diff --git a/frontend-design/references/rationale-template.md b/frontend-design/references/rationale-template.md new file mode 100644 index 0000000..20dd1e1 --- /dev/null +++ b/frontend-design/references/rationale-template.md @@ -0,0 +1,133 @@ +# Rationale Template + +Drop the following into a `design-rationale.md` alongside the code at handoff. Brief, specific, honest. Future iterations of the interface start by reading this. + +--- + +```markdown +# Design Rationale — + +**Date:** YYYY-MM-DD +**Author:** +**Invoked from:** + +## 1. Purpose + + + +## 2. Archetype + +**Chosen:** + +**Why:** + +**Trading away:** + +## 3. Locked decisions + +- **Font pairing:** for headings, for text. +- **Palette:** with . +- **Motion philosophy:** +- **Layout approach:** + +## 4. Deliberately absent + + + +## 5. Accessibility notes + +- Contrast verified at against +- Keyboard navigation: +- `prefers-reduced-motion`: +- Known concerns: + +## 6. Responsive notes + +- Primary viewport: +- Translation approach: +- Unsupported viewports (if any): + +## 7. Implementation notes + +- Framework: +- Dependencies added: +- Integration assumptions: +- Known tradeoffs: + +## 8. Open questions / follow-ups + +- [ ] +- [ ] + +## 9. References + +- Brand guide: +- Moodboard: +- Similar designs consulted: +``` + +--- + +## Filled example (abbreviated) + +```markdown +# Design Rationale — SOCOM demo landing + +**Date:** 2026-04-19 +**Author:** AI-assisted via /frontend-design +**Invoked from:** "Build a landing page for the SOCOM demo; feels technical +without being sterile." + +## 1. Purpose +Public-facing landing for the SOCOM ATAC demo. Audience: procurement +officers + technical evaluators. Must feel precise, credible, and +operationally-serious without reading as generic defense-contractor-beige. + +## 2. Archetype +**Chosen:** industrial/utilitarian with restrained editorial accents. +**Why:** Audience is operational; aesthetic distinctiveness comes from +precision, not decoration. +**Trading away:** Decorative delight; warmth. In exchange, seriousness and +signal density. + +## 3. Locked decisions +- **Font pairing:** IBM Plex Mono for headings; IBM Plex Sans for body. + (Mono carries the operational signal; sans keeps body readable.) +- **Palette:** Near-black (#0a0e0f) dominant, cool slate (#3a4851) secondary, + single desaturated amber accent (#c88c3a) used only for ATAC callouts. +- **Motion philosophy:** No motion on page load; hover states are snap-fast + (80ms). Stillness = precision. +- **Layout approach:** Grid visible as 1px cool-slate rules; content sits + inside named cells. Hero aligns to a single numbered row, not centered. + +## 4. Deliberately absent +- No hero video, no animated gradient +- No card shadows; cells share the grid rules instead +- No purple, no consumer-fintech palette cues +- No "book a demo" urgency; CTA is "Contact procurement" + +## 5. Accessibility notes +- AA verified on all text/button states +- Focus rings: 2px amber outline + offset, `:focus-visible` only +- `prefers-reduced-motion`: applies; hover transitions drop to 0ms + +## 6. Responsive notes +- Primary: desktop 1440px +- Mobile: single column, grid rules preserved; named cells stack vertically + in document order +- Below 360px: layout is acceptable but not designed for + +## 7. Implementation notes +- Framework: Next.js 14 (App Router) + Tailwind + IBM Plex (self-hosted) +- No additional deps +- Uses existing design tokens from ./lib/tokens.ts +- Integration: expects `@/components/grid` and `@/components/cell` primitives + +## 8. Open questions +- [ ] Is the amber accent readable in direct sunlight on outdoor demos? +- [ ] Legal has approved the "ATAC" wordmark treatment + +## 9. References +- Brand guide: internal/DeepSat-brand-2026-03.pdf +- Moodboard: Monokuma.com, Field Notes, NASA technical manuals +``` -- cgit v1.2.3