From 69bfac4cf643015e6d1fb26827a82538b3e46091 Mon Sep 17 00:00:00 2001 From: Remon Panman <228601219+Tradebaas@users.noreply.github.com> Date: Fri, 7 Aug 2026 18:33:47 +0200 Subject: [PATCH] refactor(skills): one rulebook for an interface, and taste is retired taste is removed. Its thirteen sections were read against impeccable's craft floor, new-work and the 59 detector rules before anything was deleted, and where each rule ended up is a table in decision 0020, which supersedes 0012 without deleting it: 0012 stays the record of why an in-house rulebook was the right answer while nothing better was installed. Two rules genuinely had no home in the method, so they moved into Groundwork files rather than disappearing. The reduced-motion obligation is now DESIGN.md principle 7: impeccable's references never state it, only its own tooling honors it, and the method builds on top of these principles and may not break them, so that is where it binds every direction. The live-surface contract on a redesign is now a fourth handover bullet in design step 3: URL structure and slugs, titles and structured data, nav labels, form field and analytics names, the wordmark, legal and consent copy. Preserve-or-overhaul itself is covered, by the method's own four-way read of what is already true. The three dials are dropped, not moved. A page configured by numeric knobs the model sets before the owner sees anything is exactly the unwatched stretch this spec closes; the method decides the same things in the open and further down, as a committed direction contract, a color strategy at page scale, and one authored motion. DESIGN.md loses the dials row with them. The denylist takes three entries: the dials notation, the upstream pointer, and the skill pointer with its path. Only the last needs an exclude, for the spec that records the retirement and says the words on purpose. Removing the explainer card left the foundation group with three, which tripped a .gcards.g3 rule that had never been exercised: three 233px columns beside 358px cards everywhere else. Dropping g3 puts the group back on the standard two-column grid, measured over CDP at 1400px, and the stat strip moved itself to 20 skills and 20 decisions because it derives both. design-guard's pointer is repointed, no more. What it should stop restating is ticket 04. Traces-to: SC-8 --- .agents/skills/design-guard/SKILL.md | 7 +- .agents/skills/design/SKILL.md | 19 +- .agents/skills/taste/SKILL.md | 308 ------------------ AGENTS.md | 1 - checks/config.json | 5 +- .../0012-taste-skill-for-persuasion-pages.md | 6 +- ...replaces-the-in-house-frontend-rulebook.md | 63 ++++ docs/design/DESIGN.md | 14 +- .../tickets/03-retire-taste.md | 14 +- index.html | 12 +- 10 files changed, 105 insertions(+), 344 deletions(-) delete mode 100644 .agents/skills/taste/SKILL.md create mode 100644 docs/decisions/0020-the-design-method-replaces-the-in-house-frontend-rulebook.md 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('');