diff --git a/.agents/skills/design-guard/SKILL.md b/.agents/skills/design-guard/SKILL.md index e88dc94..8e1bcac 100644 --- a/.agents/skills/design-guard/SKILL.md +++ b/.agents/skills/design-guard/SKILL.md @@ -8,9 +8,10 @@ description: Judgment check before delivering any UI or user-facing output: scre Render the thing (screenshot, preview, generated document) and check *that*, not the source. DESIGN.md and VOICE.md are the measuring stick; this catches what automation can't. -Is it a persuasion page (landing, marketing, portfolio, explainer)? Then skill `taste` carried -the build rules and its pre-flight already ran; this guard re-checks the rendered result, and -every `taste` section 11 tell that survived into the render is a finding here. +Is it a frontend? Then the installed design method built it, its craft floor and its detector +already ran, and a finish reviewer already scored it. Start from that verdict: re-check the render +against the direction contract in the artifact's opening comment, and report what is still open +rather than opening a fresh hunt. ## Visual diff --git a/.agents/skills/design/SKILL.md b/.agents/skills/design/SKILL.md index 865dc04..2dbd046 100644 --- a/.agents/skills/design/SKILL.md +++ b/.agents/skills/design/SKILL.md @@ -13,7 +13,7 @@ input, and holds open the three points where the owner decides. `docs/design/DESIGN.md` sections 1 and 2 and `docs/design/VOICE.md` carry the durable principles and the owner's standing defaults. DESIGN.md **section 3 is not written here**: it is recorded from -the world that was actually built, after the finish review (step 5). A rulebook written before the +the world that was actually built, after the finish review (step 4). A rulebook written before the build gets defended against reality instead of describing it. No design method installed (a project that started without an interface, a failed install recorded @@ -85,6 +85,14 @@ Then hand the method its input, once, and let it run: hand over VOICE.md section 3 and the foundation decision from step 2. - **The accessibility floor** in principle 8 and `docs/compliance/COMPLIANCE.md` is not negotiable by any direction. +- **The live-surface contract, on a redesign.** A surface that already has visitors carries + commitments the method does not know about and will not preserve on its own: URL structure and + slugs, page titles and structured data, primary navigation labels, form field names and their + order, analytics event and field names, the logo or wordmark, and legal or consent copy. Write + that list down from the live site before the direction round, hand it over as a constraint, and + check the built result against it. Anything on it that does change, changes on the owner's say-so + and ships with redirects. Losing the search ranking is the most expensive way a redesign can + succeed visually and fail commercially. The owner decides at three points, in this order. This is the order of work: @@ -114,14 +122,7 @@ The owner decides at three points, in this order. This is the order of work: An addition inside a surface that already exists inherits that surface: it is not a new identity exercise, and it does not run this round again. -## 4. Set the taste dials - -For pages meant to persuade (landing, marketing, portfolio, explainer), skill `taste` carries -the per-page execution rules. Set its three dials (VARIANCE / MOTION / DENSITY) here, from the -direction the owner chose, and record them in DESIGN.md section 3 so every later page build starts -from the same read. - -## 5. Record +## 4. Record After the finish review, DESIGN.md section 3 is written from the built world: the foundation from step 2, the tokens as they exist in code (code is the SSOT, DESIGN.md mirrors it), the component diff --git a/.agents/skills/taste/SKILL.md b/.agents/skills/taste/SKILL.md deleted file mode 100644 index f617364..0000000 --- a/.agents/skills/taste/SKILL.md +++ /dev/null @@ -1,308 +0,0 @@ ---- -name: taste -description: Anti-slop build rules for pages meant to persuade: landing pages, marketing sites, portfolios, explainers, and redesigns of those. Load before designing or building such a page, when the user asks for a landing page, marketing site, portfolio or redesign, and whenever frontend output risks the templated AI-default look. Not for dashboards, dense product UI or admin panels: there DESIGN.md and design-guard govern directly. Adapted from leonxlnx/taste-skill. ---- - -# taste: read the brief, then design past the defaults - -AI-built marketing pages fail in one recognizable way: the model skips the brief and ships its -default aesthetic. This skill is the counterweight. Infer the design language first, set three -dials, then build under rules that block the known tells. - -How it fits Groundwork: DESIGN.md (principles, tokens) and VOICE.md (language) stay the -measuring stick. `design` stands up the system once per project; this skill governs decisions -while a persuasion page is being built; `design-guard` judges the rendered result. Stack facts -and implementation patterns (component code, animation skeletons) come from -`docs/standards/.md` and live research, never from model memory. Upstream source, with -per-stack code skeletons for scroll patterns: https://github.com/leonxlnx/taste-skill (MIT). - -## 1. The design read: before any code - -Read these signals from the brief, in order: - -1. **Page kind**: landing (SaaS, consumer, agency, event), portfolio, explainer, editorial, - redesign (preserve or overhaul: section 12). -2. **Vibe words** the owner used: "minimal", "calm", "premium", "playful", "serious B2B", - "editorial", "experimental", "dark tech". -3. **References**: URLs, screenshots, named products, competitors. -4. **Audience**: the audience picks the aesthetic, not your taste. A procurement panel and a - design-conscious consumer need different pages. -5. **Existing brand assets**: logo, colors, type, photography. On redesigns these are starting - material, not optional input. -6. **Quiet constraints**: accessibility-first audiences, public sector, regulated industries, - kids' products. Constraints override aesthetic preference. - -Then declare one line before generating anything: -**"Reading this as: [page kind] for [audience], in a [vibe] language, leaning toward -[foundation or aesthetic family]."** - -Brief genuinely ambiguous? Ask exactly one question (for example "closer to Linear-clean or to -Awwwards-experimental?"), never a question dump. Confident? Declare the read and proceed. - -**Anti-default discipline.** Never reach by reflex for: purple-blue gradients, a centered hero -over a dark mesh, three equal feature cards, glassmorphism on everything, infinite -micro-animations, Inter plus slate-900. Those are model defaults, not decisions -(DESIGN.md principle 10 is the standing ban). - -## 2. Set the three dials - -Every layout, motion, and density decision below is gated by three dials (1 to 10): - -- **VARIANCE**: 1 = perfect symmetry, 10 = artistic chaos -- **MOTION**: 1 = static, 10 = cinematic choreography -- **DENSITY**: 1 = art gallery, 10 = cockpit - -Infer the values from the design read; state them with the read and record them in DESIGN.md -section 3. Presets (VARIANCE / MOTION / DENSITY): - -| Read | Dials | -|---|---| -| Minimal, calm, editorial, Linear-register | 5 / 3 / 3 | -| Landing, SaaS mainstream | 7 / 6 / 4 | -| Landing, agency or creative | 9 / 8 / 3 | -| Premium consumer, luxury | 7 / 6 / 3 | -| Portfolio (designer 8/7/3, developer 6/5/4) | see left | -| Trust-first, public sector, regulated | 3 / 2 / 5 | -| Redesign, preserve | match existing, motion +1 | -| Redesign, overhaul | variance +2, motion +2 | - -Dial meaning in practice: low VARIANCE is a symmetric grid; 4-7 allows offsets, mixed aspect -ratios; 8+ allows masonry, fractional grids, large deliberate empty zones. Low MOTION is hover -and focus states only; 4-7 is eased transitions and load-in cascades; 8+ is scroll-driven -choreography. Low DENSITY is huge section gaps; high DENSITY drops card boxes for hairlines and -sets numbers in mono. High-variance layouts always collapse to a strict single column below -tablet width; declare that fallback in the same component, never assume it. - -## 3. Choose the foundation honestly - -- The project's UI foundation decision (`design` step 2, decision pattern 0009) binds here: one - foundation per project, brand tokens on top, no second system introduced for one page. -- If the brief reads like an established design system (enterprise SaaS, Material-flavored, - public-sector GOV.UK/USWDS register, Shopify or Atlassian surface), use the official package - for it. Never recreate a known system's CSS by hand, and never import a system's tokens only - to override most of them. -- If the brief is an aesthetic without an official package (glassmorphism, bento, brutalism, - editorial, dark tech, kinetic typography), build it with the project's own tokens and say so - in comments: borrowed inspiration, not an official system. "Apple Liquid Glass" on the web is - always a labeled approximation. -- Verify current package names, versions, and install commands live (`stack` skill territory); - check the dependency exists in the project before importing anything. - -## 4. Layout rules - -**Hero.** -- Fits the initial viewport: headline at most 2 lines, subtext at most 20 words and 4 lines, - primary CTA visible without scrolling. Too much copy means the value proposition is unclear; - cut copy, do not shrink the rule. -- Plan font scale and hero asset together. A 4-line hero headline is a font-size error. -- Top padding capped around 6rem desktop; hero content never floats halfway down the viewport. -- At most 4 text elements: one eyebrow OR brand strip (or neither), headline, subtext, CTAs - (1 primary, at most 1 secondary). No trust micro-strip, pricing teaser, tagline under the - CTAs, or feature bullets inside the hero; those get their own section below. -- The hero needs a real visual (section 7). Text plus a gradient blob is a placeholder. -- A "trusted by" logo wall lives in its own section under the hero, never inside it. -- Centered heroes only when VARIANCE is 4 or lower or the brief is a manifesto; otherwise - split, asymmetric, or left-aligned compositions. - -**Navigation.** One line at desktop (condense or move to a menu if it does not fit), height at -most 80px, default 64-72px. - -**Section rhythm.** -- **Eyebrow rationing**: at most 1 small uppercase label above a heading per 3 sections, hero - included. The check is mechanical: count uppercase-tracked micro-labels; more than - ceil(sections / 3) fails. Default alternative: no eyebrow, the headline is enough. -- **Layout family repetition**: a layout family (3-column cards, full-width quote, - image-text split, bento) appears at most once per page; a page of 8 sections needs at least - 4 different families. -- **Zigzag cap**: at most 2 consecutive image-text-split sections; break the third with a - full-width section, vertical stack, bento, or marquee. -- **Split-header ban**: no "big headline left, small explainer paragraph floating right" as a - section header. Stack them: headline, then body at readable measure. The split earns its - place only when the right column carries a real visual or interactive element. - -**Bento and grids.** -- Exactly as many cells as there is content; never a filler or empty tile. -- Background diversity: in any multi-cell grid, 2-3 cells carry a real image, tint, or pattern; - all-white text cards read as template output. -- Grid over flex arithmetic: CSS grid with explicit columns, never percentage calc chains. -- Full-height sections use dynamic viewport units, not the static viewport height that jumps on - mobile browsers. - -## 5. Typography - -- The project's type tokens (DESIGN.md section 3) bind. One family, few weights, scale steps - only; hierarchy by size and color before weight. -- **Sans display is the default** for creative, premium, agency, and portfolio briefs alike. - "Creative brief, so serif" is the single most-tested AI tell. A serif is justified only when - the brand brief names one, or the register is genuinely editorial, luxury, publication, or - heritage AND you can articulate why that serif fits that brand. Never reuse the same serif - across consecutive projects, and never reach for the two LLM-favorite display serifs - (Fraunces, Instrument Serif) by default. -- **Emphasis inside a headline**: italic or bold of the same family. Never a serif word - injected into a sans headline for visual interest. -- **Italic descenders**: an italic display word containing y, g, j, p, or q clips under tight - leading; keep line-height at least 1.1 and reserve bottom padding. -- Body text at a readable measure (about 65 characters); no oversized screaming headlines, - hierarchy comes from weight and color before raw scale. - -## 6. Color and theme - -- One accent family, locked page-wide (DESIGN.md principles 2 and 10). A warm-gray page does - not get a blue CTA in section 7; audit every component against the lock before shipping. -- Neutral base, saturation restrained; accent chosen for the brand, not the model's habit. - If the brand genuinely is purple, execute purple with intent; the ban is on the reflex. -- **Premium-consumer palette rotation**: for luxury, artisan, wellness, and craft briefs the - AI default is warm cream backgrounds with brass, clay, or oxblood accents and espresso text. - Banned as a reflex. Rotate real alternatives: cold luxury (silver, chrome, smoke), forest - (deep green, bone, amber), true off-black with warm tan, cobalt with cream, terracotta with - slate, olive with brick, or monochrome with one saturated pop. Only use the cream-and-brass - family when the brand brief names those colors and you can say why. -- **Theme lock**: one theme (light, dark, or system) per page, set at the root. Sections never - flip to the inverted mode mid-scroll; background tints stay within the theme family. A - deliberate full theme switch as a story device is allowed once per page, only when the brief - asks for it. -- Design both modes from the start when the platform supports it; keep hierarchy, brand - recognition, and contrast in both. No pure black or pure white surfaces; off-black and - off-white keep depth. Test both modes before finishing. - -## 7. Imagery and assets - -Persuasion pages are visual products; a text-only page is not minimalism, it is unfinished. - -Priority order for images: -1. **An image-generation tool** available in the environment: use it for section-specific - assets (hero, product, texture, mood) at the right aspect ratio. -2. **Real photography**: brand assets from the brief, or seeded placeholder photography - (picsum with a descriptive seed) and openly licensed sources when allowed. -3. **Neither available**: leave clearly labeled placeholder slots with exact dimensions and - tell the owner which images are needed. Never fill the gap with hand-rolled SVG - illustrations or fake screenshots built from styled divs. - -Hard rules: -- **No div-built fake product UI** (fake task lists, fake terminals, fake dashboards). Use a - real screenshot, a generated image, a real live component preview, or nothing. -- **Logo walls** use real SVG marks (Simple Icons or the brand's own files), never styled text - wordmarks; invented brands get a simple generated SVG monogram. Logos only: no category - labels under them. Logos must work in both themes. -- **Icons**: one family per project, from the owner's standing default in DESIGN.md - (principle 9); lock one stroke width; never hand-drawn icon paths, never emoji as icons. -- Hand-rolled decorative SVG only when the brief asks for it and the mark is simple geometry. - -## 8. Copy on the page - -VOICE.md governs all language, including the mechanically enforced typography bans and the -banned-phrase list. On top of that, for persuasion pages: - -- **Copy self-audit before done**: reread every visible string (headlines, buttons, captions, - alt text, footer). Rewrite anything grammatically broken, cute-but-unclear, mock-poetic, or - performatively humble. Plain beats clever-but-wrong, every time. -- **Fake-precise numbers**: statistics and spec values either come from real data, or are - explicitly labeled as sample data, or they go. Never invent engineering precision. -- **Believable content**: no placeholder-people names (the "Jane Doe" effect), no generic - egg avatars, no startup-slop brand names; use locale-appropriate, specific, realistic data. -- **Quotes**: at most 3 lines of body, real typographic quotes or none, attribution with name - plus role (never a bare first name). -- **One copy register per page**: do not mix technical mono metadata, editorial prose, and - marketing punch unless the brand voice explicitly does. -- CTA labels: at most 3 words, one label per intent for the whole page ("Get in touch" and - "Let's talk" on one page is a fail), never wrapping to a second line at desktop. - -## 9. Motion - -- **Motion must be motivated.** Before adding any animation, name what it communicates: - hierarchy, storytelling, feedback, or state transition. "It looks cool" is not a reason; an - animation you cannot justify in one sentence gets cut. -- **Motion claimed is motion shown.** MOTION above 4 means the page actually moves: hero - entrance, scroll reveals on key sections, hover physics on CTAs. Cannot ship working motion - in scope? Drop the dial to 3 and ship clean static; never half-working choreography. -- **Reduced motion is mandatory** above MOTION 3: infinite loops, parallax, scroll hijacks, and - pointer physics all collapse to static under the user's reduced-motion preference. -- Animate only transform and opacity; never top, left, width, height. No raw scroll-event - listeners or per-frame state updates; use the platform's observer or scroll-driven APIs, or - the animation library's scroll primitives (per `docs/standards/.md`). -- At most one marquee per page. One animation library per component tree. Grain and noise - overlays only on fixed non-interactive layers, never on scrolling containers. -- Scroll-pinned patterns (sticky stacks, horizontal pans) follow the canonical skeletons in the - upstream repo: pin at viewport top, scrub the inner track, clean up on unmount. -- DESIGN.md principle 7 (nothing moves uncaused) stays the default for product UI; a persuasion - page may raise MOTION deliberately, within the rules above. - -## 10. States and accessibility - -- Full state cycles, not the happy path: skeleton loaders shaped like the final layout, empty - states that say what to do, inline error states. -- **Button and form contrast**: every CTA readable against its background (WCAG AA, 4.5:1 body, - 3:1 large text); ghost buttons over photography get a scrim or border. Inputs, placeholders, - focus rings, helper and error text all pass contrast against their section background. -- Labels above inputs, error text below, never placeholder-as-label. -- Tactile press feedback on interactive elements (a 1px translate or 2 percent scale). -- The accessibility floor of DESIGN.md principle 8 and COMPLIANCE.md applies unchanged. - -## 11. Forbidden tells (hard bans, brief-override only) - -The recognizable signatures of AI-generated pages. Each is banned unless the brief explicitly -asks for it: - -- Version labels in the hero (BETA, EARLY ACCESS, v0.6) outside a genuine launch brief. -- Section-number eyebrows ("001 / Capabilities"), pagination labels on tiles, numbered scroll - cues, "index of work" range labels, generic step labels ("Step 1 / Step 2": the verb is the - label). -- Scroll cues of any kind ("scroll to explore", animated mouse icons). -- Decorative status dots on nav items, list rows, or badges; a dot only ever shows real - semantic state, at most one per section. -- Locale, time, or weather strips ("LIS 14:23, 18 degrees") unless the product is genuinely - place- or timezone-centric; a plain footer address is fine. -- Pills or tags overlaid on photos; photo-credit captions as decoration; version footers on - marketing pages; live-stock counters without real data. -- Decoration text strips at the hero bottom ("DESIGN. BUILD. SHIP.") unless they are real - navigation. -- Poetic section labels ("From the field", "On our desks"); "Quietly trusted by" social-proof - headers; micro-meta sentences under eyebrows. Plain functional labels or none. -- Hairline crosshair grids as pure decoration; vertical rotated text outside genuinely - experimental briefs; broken-and-italicized headline splits as a default move. -- Both a top and bottom border on every row of a long list; scoring bars with filled background - tracks as comparison visuals on a marketing page. -- Long lists as bare bulleted lists: more than 5 items wants grouped chunks, a card grid, tabs, - scroll-snap pills, or a "view full list" disclosure. -- Custom mouse cursors, neon outer glows, oversaturated accents, gradient text on large - headers. -- Middle dots as the universal separator (at most one per metadata line). -- Em and en dashes anywhere on the page: already mechanically banned repo-wide (VOICE.md, - `checks/check.mjs`), and doubly a tell in rendered UI. - -## 12. Redesign protocol - -Misreading the mode is the biggest source of bad redesign output. Detect it first: greenfield, -preserve (modernize without breaking the brand), or overhaul (new visual language, same content -and structure). Ambiguous? Ask once. - -**Audit before touching**: current brand tokens, information architecture and conversion paths, -which content blocks do work and which are filler, signature patterns to keep, tells and broken -layouts to retire, the existing site's dial reading (that is the starting point, not the -baseline), and the SEO baseline (slugs, titles, structured data): SEO migration is the top -redesign risk. - -**Preserve unless asked**: information architecture, slugs and anchors, nav labels, copy voice, -existing accessibility wins, analytics-tracked names and form fields. - -**Modernization levers, in order of lift per unit of risk**: typography refresh; spacing and -rhythm; color recalibration (keep the brand accent); a motion layer on existing components; -hero and key-section recomposition; full block replacement only when a block is unsalvageable. -Sound structure and content? Targeted evolution (levers 1-4) gives most of the value at less -than half the risk of a full redesign. - -**Never change silently**: URL structure, primary nav labels, form field names or order, the -logo or wordmark, legal and consent copy. - -## 13. Pre-flight, then design-guard - -Before calling the page done, check the built output against this skill: design read declared; -dials stated and recorded; hero within budget (2-line headline, 20-word subtext, 4 text -elements, CTA above the fold, real visual); eyebrow count within ration; no repeated layout -family; accent and theme locked page-wide; serif and palette justified or absent; every CTA -contrasting, non-wrapping, one label per intent; real images, no fake screenshots; copy -self-audited; every animation motivated and reduced-motion safe; full state cycles present; no -tell from section 11. Any miss means the page is not done. - -Then render it and run `design-guard` on the result, as always. Report the design read, the -dials, and any deliberate overrides (with their reason) in one short block. ⚓ diff --git a/AGENTS.md b/AGENTS.md index b0ffbd7..6ac57ac 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -105,7 +105,6 @@ trigger applies. The library: | `stack` | Choosing the tech stack or hosted platform; generates `docs/standards/.md`, wires gates | | `architect` | System design before building: boundaries, data, contracts, threats | | `design` | Standing up the project's design & voice system | -| `taste` | Building or redesigning a landing page, marketing site, portfolio or explainer | | `scope-guard` | Before calling work done or proposing a commit | | `design-guard` | Before delivering any UI or user-facing output | | `verify` | Verifying a change actually works, end to end | diff --git a/checks/config.json b/checks/config.json index 6fd3ff1..9d44b8a 100644 --- a/checks/config.json +++ b/checks/config.json @@ -16,7 +16,10 @@ { "pattern": "skipSymlinkCheck\"?\\s*:\\s*true", "why": "retired instruction; skipSymlinkCheck takes the reason as a string value and config-invariants rejects a bare true, so an exemption states its case (INTAKE row 58)" }, { "pattern": "COMPLIANCE\\.md.{0,4}§ ?[12]|§ ?[12].{0,40}COMPLIANCE\\.md", "why": "retired pointer; COMPLIANCE.md is one table of regimes with no numbered sections, and this project's register moved to docs/compliance/REGISTER.md, which begin copies from TEMPLATE-REGISTER.md" }, { "pattern": "clear §2 back to its skeleton", "why": "retired begin instruction; the register is a cp from docs/compliance/TEMPLATE-REGISTER.md now, like the brief, the deploy runbook and the debt ledger" }, - { "pattern": "definitions cover language|no implementation detail in this file", "why": "retired glossary rule; a CONTEXT.md entry may now settle how a term is measured (which period, which basis, who counts) and stops at the threshold value and the branching, which belong in a spec where a test can execute them (decision 0019)" } + { "pattern": "definitions cover language|no implementation detail in this file", "why": "retired glossary rule; a CONTEXT.md entry may now settle how a term is measured (which period, which basis, who counts) and stops at the threshold value and the branching, which belong in a spec where a test can execute them (decision 0019)" }, + { "pattern": "\\btaste dials\\b|VARIANCE ?/ ?MOTION ?/ ?DENSITY", "why": "retired taste-skill machinery; a page is no longer configured by three numeric knobs set before the owner sees anything. The installed design method commits a direction contract, a color strategy and one authored motion instead (decision 0020)" }, + { "pattern": "leonxlnx/taste-skill", "why": "retired upstream pointer; the frontend rulebook this repo adapted from it is gone and the installed design method owns that ground now (decision 0020 supersedes 0012)" }, + { "pattern": "skill `taste`|\\.agents/skills/taste", "why": "retired skill; taste was removed on 2026-08-07 and nothing may point at it again. What each of its rules became is the table in decision 0020", "exclude": ["docs/specs/011-design-on-impeccable/"] } ], "styleBans": [ { "pattern": "\\bdelve(s|d|ing)?\\b", "why": "AI-tell verb; say 'look at', 'go into' or just state the point" }, diff --git a/docs/decisions/0012-taste-skill-for-persuasion-pages.md b/docs/decisions/0012-taste-skill-for-persuasion-pages.md index 4450c65..235be24 100644 --- a/docs/decisions/0012-taste-skill-for-persuasion-pages.md +++ b/docs/decisions/0012-taste-skill-for-persuasion-pages.md @@ -1,6 +1,10 @@ # 0012: Frontend persuasion pages follow the `taste` skill, adapted from leonxlnx/taste-skill -- **Date:** 2026-07-11 · **Status:** accepted · **Decider:** owner (Remon) + agent +- **Date:** 2026-07-11 · **Status:** superseded by 0020 · **Decider:** owner (Remon) + agent + + ## Context diff --git a/docs/decisions/0020-the-design-method-replaces-the-in-house-frontend-rulebook.md b/docs/decisions/0020-the-design-method-replaces-the-in-house-frontend-rulebook.md new file mode 100644 index 0000000..d7aec6e --- /dev/null +++ b/docs/decisions/0020-the-design-method-replaces-the-in-house-frontend-rulebook.md @@ -0,0 +1,63 @@ +# 0020: The installed design method replaces Groundwork's in-house frontend rulebook + +- **Date:** 2026-08-07 · **Status:** accepted · **Decider:** owner (Remon) + agent + +## Context + +Decision 0012 gave this framework `taste`: an adapted, in-house rulebook for the page type models +fail at most visibly. It was the right answer while nothing better was installed. Spec 011 installs +impeccable per project as the method that makes an interface, and impeccable carries its own craft +floor, its own list of category defaults to refuse, and a deterministic detector of 59 rules. Two +anti-slop rulebooks side by side is exactly the situation AGENTS.md exists to prevent: one fact, +one place. The owner chose retirement over coexistence on 2026-08-05. + +## Options considered + +1. **Retire `taste`, move what the method does not carry to the file that owns it (chosen):** one + rulebook governs a build, and the pieces that are genuinely Groundwork's (the accessibility + floor, the live-surface contract, the foundation choice) live where they were already owned. +2. **Keep both, `taste` for persuasion pages and the method for the rest:** every page type would + need a routing rule, and the two would drift on the first upstream release. A build would have + to be judged against two lists that disagree. +3. **Keep `taste` as the house overlay on top of the method:** an overlay is a patch on somebody + else's file by another name, and it re-creates the update cost the per-project install exists to + avoid (spec 011's settled decisions). + +## Where each retired rule went + +| `taste` section | Where it lives now | +|---|---| +| 1 Design read | Method: new-work section 1 (what is already true) and 2 (one round of questions per mode) | +| 2 Three dials (VARIANCE / MOTION / DENSITY) | **Dropped.** See below | +| 3 Foundation choice | Unchanged and unmoved: `design` step 2 and decision 0009. `taste` only restated it | +| 4 Layout rules | Method: craft floor (cards, nested cards, kicker ban, section numbers, spacing), new-work section 6 (first viewport, scroll pacing); detector rules `kicker-above-heading`, `hero-eyebrow-chip`, `numbered-section-labels`, `oversized-h1`, `edge-flush-cards`, `cramped-padding`, `monotonous-spacing` | +| 5 Typography | Method: craft floor (measure, scale, tracking floor), new-work section 4 (face selection, with its own list of overused faces); detector `overused-font`, `italic-serif-display`, `flat-type-hierarchy`, `line-length`, `tiny-text`, `wide-tracking`, `tight-leading` | +| 6 Color and theme | Method: new-work section 4 (color strategy, the named default-palette calibration, light or dark chosen from the use scene); detector `ai-color-palette`, `cream-palette`, `gradient-text`, `dark-glow`, `radial-halo`. The rule to design both light and dark from the start is **dropped**: the method picks one theme from the real use scene, and a surface that needs both says so in its own brief | +| 7 Imagery and assets | Method: craft floor (no glyphs for icons, no chrome standing in for content), new-work section 6 (author the assets, verified real imagery); detector `shape-assembled-illustration`, `broken-image`, `icon-tile-stack`. The icon family stays the owner's default in DESIGN.md principle 9 | +| 8 Copy on the page | VOICE.md and the prose gate keep language, unchanged. Method: craft floor (the product's own language), `clarify`, and the truth rule in new-work section 3 (claims stay uninventable, demonstration data is labelled); detector `marketing-buzzword`, `aphoristic-cadence`, `theater-slop-phrase`, `em-dash-overuse` | +| 9 Motion | Method: craft floor (one authored moment), new-work section 6 (motion as the form's own material); detector `bounce-easing`, `layout-transition`, `marquee`, `pulsing-dot`, `content-hidden-at-rest`. **Moved:** the reduced-motion obligation, which the method's own guidance never states, is now DESIGN.md principle 7, where it binds every direction | +| 10 States and accessibility | Method: craft floor (states, contrast); detector `low-contrast`, `gray-on-color`. The legal floor stays DESIGN.md principle 8 and COMPLIANCE.md | +| 11 Forbidden tells | Method: the craft floor's Refuse list and the 59 detector rules. Ticket 05 makes the detector a gate | +| 12 Redesign protocol | Preserve-or-overhaul is the method's own four-way read (new-work section 1, plus "refinement preserves, redesign replaces"). **Moved:** the SEO and migration half, which the method does not carry at all, is now the live-surface contract in `design` step 3: URLs and slugs, titles and structured data, nav labels, form field and analytics names, wordmark, legal and consent copy | +| 13 Pre-flight | Method: the finish reviewer and its verdict, reported with its open items (`design` step 3). `design-guard` re-checks the render against the direction contract | + +**Why the dials are dropped rather than moved.** They are a model-set configuration of a page, +fixed before the owner sees anything, which is precisely the unwatched stretch spec 011 exists to +close. The method decides the same things in the open and further down: a committed direction +contract, a color strategy chosen at page scale, and motion authored once as the form's own. A +numeric knob beside that contract would be a second, weaker answer to a question already settled. + +## Decision & consequences + +`taste` is gone from `.agents/skills/`, from the AGENTS.md table, from DESIGN.md principle 10, from +`design`, from `design-guard` and from the explainer. Decision 0012 is superseded, not deleted: it +stays the record of why an in-house rulebook was right while nothing better was installed. The +retired wording is in the denylist in `checks/config.json`, so the dials and the upstream pointer +cannot quietly return in a later session. + +Easier: one rulebook governs a build, and it updates by reinstalling rather than by hand. Harder: +the rules now live in somebody else's file, so a rule this framework wants to keep has to be +carried in a Groundwork file, as the reduced-motion floor and the live-surface contract now are. +Watch for: an upstream release that drops a rule the table above credits to it. `maintain`'s +dependency round is where that gets noticed, and the answer is to move the rule back into a +Groundwork file, never to fork the method. diff --git a/docs/design/DESIGN.md b/docs/design/DESIGN.md index 9752c0f..3a48e2d 100644 --- a/docs/design/DESIGN.md +++ b/docs/design/DESIGN.md @@ -25,7 +25,10 @@ 6. **States are designed, not inherited.** Hover, visible focus, disabled, loading, empty, error: every component ships with all of them. Empty states say what to do, not just "no data". 7. **Motion is physics, not decoration.** 120-200ms ease-out on state changes; nothing bounces, - nothing autoplays, nothing moves that the user didn't cause. + nothing autoplays, nothing moves that the user didn't cause. A chosen direction may author more + motion than that on a surface meant to persuade, and whatever it authors collapses to static + under the user's reduced-motion preference: loops, parallax, scroll-driven choreography and + pointer physics all go still there, with the content still readable. 8. **Accessible by construction.** Contrast of at least 4.5:1 for text, focus always visible, touch targets at least 44px, semantics before ARIA. WCAG 2.1 AA is the legal floor, not the ambition. @@ -38,10 +41,9 @@ gradient, and blue or purple as a reflex accent, are banned as defaults; pick the project's own accent (seed: the owner's deep teal). A gradient is only ever a small, deliberate, owner-approved accent, never the baseline. Any background motion stays subtle and secondary - to reading; usability wins over decoration. For pages meant to persuade (landing, marketing, - portfolio, explainer) the full anti-slop rulebook is skill `taste`: brief read first, three - dials, layout and motion rules, forbidden tells. There a deliberately higher motion level - may override principle 7, within `taste`'s reduced-motion and motivation rules. + to reading; usability wins over decoration. The full rulebook against the default look is the + installed design method's craft floor and its detector, which the skill `design` runs; these + ten principles are the floor it builds on top of and may not break. ## 2. Standing default direction (the owner's taste: seed, not straitjacket) @@ -68,8 +70,6 @@ the `design` skill; deviate only on the owner's say-so. | Accent | `--color-accent` | TBD | one family, sparingly | | Danger / Warning / Success / Info | `--color-...` | TBD | used via opacity only | -- **Taste dials:** TBD - **Type scale:** TBD - **Spacing ladder:** TBD - **Radius:** TBD diff --git a/docs/specs/011-design-on-impeccable/tickets/03-retire-taste.md b/docs/specs/011-design-on-impeccable/tickets/03-retire-taste.md index a892a08..88bf207 100644 --- a/docs/specs/011-design-on-impeccable/tickets/03-retire-taste.md +++ b/docs/specs/011-design-on-impeccable/tickets/03-retire-taste.md @@ -1,7 +1,7 @@ # 03: taste is retired, and nothing points at a skill that is gone - **Blocked by:** 02-begin-and-design-route-into-impeccable.md -- **Status:** ready +- **Status:** done - **Traces to:** BRIEF SC-8 **What to build:** The framework carries one rulebook for building an interface. `taste` is @@ -15,13 +15,13 @@ decision record states where each went. **Acceptance:** -- [ ] Every rule in `taste` is accounted for: covered by impeccable, moved to a named file, or +- [x] Every rule in `taste` is accounted for: covered by impeccable, moved to a named file, or dropped with a reason. The mapping is written in the decision record, not in a commit message. -- [ ] `.agents/skills/taste/` is gone and its row is out of the AGENTS.md skills table. -- [ ] Every pointer that named it is repointed: DESIGN.md principle 10, `design`, `design-guard`, +- [x] `.agents/skills/taste/` is gone and its row is out of the AGENTS.md skills table. +- [x] Every pointer that named it is repointed: DESIGN.md principle 10, `design`, `design-guard`, and any doc the links gate finds. -- [ ] Decision 0012 is marked superseded, naming the decision that replaced it, and stays readable +- [x] Decision 0012 is marked superseded, naming the decision that replaced it, and stays readable as the record of why the earlier choice was right at the time. -- [ ] The retired wording is in the denylist in `checks/config.json`, so a later session cannot +- [x] The retired wording is in the denylist in `checks/config.json`, so a later session cannot reintroduce a rulebook that no longer exists. -- [ ] `node checks/check.mjs`, the links gate and the self-test suites stay green. +- [x] `node checks/check.mjs`, the links gate and the self-test suites stay green. diff --git a/index.html b/index.html index 9ae9ba9..7bd4982 100644 --- a/index.html +++ b/index.html @@ -236,7 +236,6 @@ .glabel{font-size:14.5px;font-weight:600;color:var(--ink);letter-spacing:-.01em;padding-top:2px} .glabel small{display:block;font-size:12.5px;color:var(--muted);font-weight:400;margin-top:5px} .gcards{display:grid;grid-template-columns:1fr 1fr;gap:16px} - .gcards.g3{grid-template-columns:repeat(3,1fr)} .card{background:var(--surface);border:1px solid var(--line);border-radius:var(--r); padding:18px 20px;transition:border-color .2s} .card:hover{border-color:var(--line2)} @@ -244,7 +243,7 @@ font-weight:600;color:var(--ink)} .card p{color:var(--ink2);font-size:13.5px;line-height:1.6;margin-top:7px} @media(max-width:820px){.sgroup{grid-template-columns:1fr;gap:16px}} - @media(max-width:600px){.gcards,.gcards.g3{grid-template-columns:1fr}} + @media(max-width:600px){.gcards{grid-template-columns:1fr}} .reveal{opacity:0;transform:translateY(24px);transition:opacity .65s ease,transform .65s cubic-bezier(.2,.7,.2,1)} .reveal.vis{opacity:1;transform:none} @@ -462,9 +461,9 @@

From idea to product, without the mess

the owning directory and turns red when this page drifts. The two unmarked stats are claims, not counts. Copied this repo to start a product? `begin` drops these markers: the numbers then describe the framework you copied, not what you are building. --> -
21
Skills on demand
+
20
Skills on demand
22
Automated checks
-
19
Recorded decisions
+
20
Recorded decisions
1
Rulebook, every tool
0
Tokens for the checks
@@ -839,8 +838,7 @@

Look

['Laying the foundation','technology, structure and taste',[ ['stack','Chooses the technology and looks up live what the right, safe way to use it is today.'], ['architect','Designs the system: the boundaries, the data, the integrations and the threats it faces.'], - ['design','Sets up the visual system and the writing style, tuned to your taste and your audience.'], - ['taste','Build rules against the default AI look for landing pages, marketing and portfolios: read the brief first, then design past the templates.']]], + ['design','Sets up the visual system and the writing style, tuned to your taste and your audience, and runs the making of a screen through the installed design method.']]], ['Guarding quality','fresh eyes on every result',[ ['scope-guard','The last check before work is called "done": was nothing extra built that nobody asked for?'], ['design-guard','The last check on screens and texts before they go out the door.'], @@ -861,7 +859,7 @@

Look

var sg=document.getElementById('skillgrid'); sg.innerHTML=skillGroups.map(function(g){ return '

'+g[0]+''+g[1]+'

'+ - '
'+g[2].map(function(s){ + '
'+g[2].map(function(s){ return '
'+s[0]+'

'+s[1]+'

'; }).join('')+'
'; }).join('');