RegionallyFamous · nickhamze · Apr 29, 2026
@@ -0,0 +1,74 @@
+# Cog — design brief
+
+This file was emitted by `bin/design.py` after cloning `obel` -> `cog` and applying the spec's palette + font choices. Read it before you do anything else; it captures the design intent the spec encoded so you can write the per-theme microcopy block, restyle the templates that need it, and brief any product photography in the same voice.
+
+## Tagline
+
+> oil-stained cream, scarlet, sprocket icons, exploded diagrams
+
+## Voice
+
+contemporary gear-tool store: warm, direct, no exclamation marks.
+
+Write this voice into the `// === BEGIN wc microcopy ===` block in `cog/functions.php`. Every theme's microcopy must read distinctly from every other theme's; `bin/check.py check_wc_microcopy_distinct_across_themes` enforces it. Crib the structure from any sibling theme's microcopy block, then rewrite every literal string in this voice.
+
+## Layout hints
+
+- labelled diagram as the hero centerpiece
+- caption strip beneath the diagram
+- three-up product grid below
+
+These hints came from the spec. Restructure `templates/front-page.html` and any sibling templates whose composition needs to change. Token swaps alone are never enough; see `.claude/skills/build-block-theme-variant/SKILL.md` step 6.
+
+## Palette applied
+
+| Slug | Hex |
+|------|-----|
+| `accent` | `#c8281a` |
+| `accent-soft` | `#ecb4af` |
+| `base` | `#f5efe6` |
+| `border` | `#b8b3ac` |
+| `contrast` | `#2b2b2b` |
+| `muted` | `#fcfaf8` |
+| `primary` | `#2b2b2b` |
+| `primary-hover` | `#555555` |
+| `secondary` | `#222222` |
+| `subtle` | `#f9f5f0` |
+| `surface` | `#ffffff` |
+| `tertiary` | `#1a1a1a` |
+
+Run `python3 bin/check-contrast.py` (if it exists in this repo) before locking the palette. Verify every pairing in the WCAG table at `.claude/skills/build-block-theme-variant/SKILL.md` step 5.
+
+## Fonts registered
+
+**Google Fonts to download as `.woff2`** (the `fontFace` entries already
+point at `cog/assets/fonts/<slug>-<weight>.woff2` — drop the files there):
+
+- `Bebas Neue` (display, weights 400, 700)
+- `Inter` (sans, weights 400, 600)
+
+Use https://gwfh.mranftl.com/fonts to pull the official `.woff2` files (one per weight + style). Then run `python3 bin/check.py check_no_remote_fonts` to confirm no remote URLs slipped in.
+
+## Next steps
+
+1. Open `theme.json` and confirm the palette / font slots match your intent.
+2. Drop product photographs as `cog/playground/images/product-wo-*.jpg` 
+   (one per product). Generate them so they read as this theme's voice;
+   `bin/check.py check_product_images_unique_across_themes` will reject any
+   byte-shared with a sibling theme.
+3. Edit the `// === BEGIN wc microcopy ===` block in `functions.php` to match
+   the voice above.
+4. Restructure `templates/front-page.html` per the layout hints; every theme's
+   homepage must be structurally distinct (`check_front_page_unique_layout`).
+5. Re-shoot screenshot.png: `python3 bin/build-theme-screenshots.py cog`.
+6. Snap baseline: `python3 bin/snap.py shoot cog && \
+   python3 bin/snap.py baseline cog`.
+7. Verify: `python3 bin/check.py cog --quick` — fix every failure before
+   committing. Don't suppress with `--no-verify`.
+8. Commit + push everything (theme dir, blueprint, content, baselines).
+
+`BRIEF.md` is committed alongside the theme so future agents (and the next
+human reading the repo a year from now) can see the design intent that
+seeded the theme without spelunking the original prompt.
+
+_Brief auto-generated for cog by `bin/design.py`._
@@ -0,0 +1,65 @@
+# Changelog
+
+Versions follow [Semantic Versioning](https://semver.org/). Append new entries to the top.
+
+## 1.0.0
+
+Initial release.
+
+A block-only WooCommerce starter theme. All visual styling lives in `theme.json`. No custom CSS files, no custom blocks, no patterns library that ships activated by default. The intended workflow is to copy the theme folder, rename it for the project, and edit `theme.json`.
+
+### Templates and parts
+
+- WordPress templates: `index`, `home`, `front-page`, `singular`, `single`, `page`, `archive`, `category`, `tag`, `author`, `date`, `taxonomy`, `search`, `404`.
+- WooCommerce templates: `single-product`, `archive-product` (also handles `product_cat` / `product_tag` / `product_attribute` archives via the WP template hierarchy fallback), `product-search-results`, `page-cart`, `page-checkout`, `order-confirmation`, `page-coming-soon`.
+- Custom page templates: `page-no-title`, `page-full-width`, `page-landing`.
+- Template parts: `header`, `checkout-header`, `footer`, `comments`, `post-meta`, `product-meta`, `no-results`.
+
+### Design system (`theme.json`)
+
+- Single source of truth for color, typography, spacing, shadow, radius, border, layout, line-height, letter-spacing, font-weight, transition, cover height, and aspect-ratio tokens.
+- ~100 block style entries covering every `core/*` and `woocommerce/*` block referenced by the templates.
+- Block style variations: `core/group` (`card`, `panel`, `callout`, `surface`), `core/button` (`outline`), `core/separator` (`wide`, `dots`).
+- `core/image` lightbox enabled by default.
+- Three style variations in `styles/`: `dark`, `editorial`, `high-contrast`.
+
+### Edit-one-value-ripples-everywhere tokens
+
+Every layout width, cover height, and aspect ratio used in markup is a CSS variable. Editing one value in `theme.json` propagates through every template, part, and pattern.
+
+- `settings.layout.contentSize` (720px) drives every prose-width container; templates do not override it.
+- `settings.layout.wideSize` (1280px) is referenced via `var(--wp--style--global--wide-size)` in header, footer, checkout-header, and front-page sections.
+- `settings.custom.layout` defines `narrow` (480px), `prose` (560px), `comfortable` (640px) for special containers.
+- `settings.custom.cover` defines `hero` (640px), `promo` (520px), `tile` (320px) for cover `min-height`.
+- `settings.custom.aspect-ratio` defines `square`, `portrait`, `card`, `widescreen` for `core/post-featured-image` and `woocommerce/product-image`.
+- `settings.custom.border.width` defines `hairline` (1px), `thick` (2px).
+
+### Starter patterns
+
+Eleven generic patterns in `patterns/`: `hero-image`, `hero-text`, `featured-products`, `value-props`, `faq-accordion`, `testimonials`, `brand-story`, `newsletter`, `cta-banner`, `footer-columns`, `category-tiles`. Six pattern categories registered: `cog`, `woo-commerce`, `featured`, `call-to-action`, `testimonials`, `footer`.
+
+### Tooling (`bin/`)
+
+- `check.py` — single-command validator. Runs JSON validity, PHP syntax, block-name validity (against Gutenberg + WooCommerce trunk), `INDEX.md` freshness, `!important` scan, stray-`.css` scan, block-namespace scan, AI-fingerprint scan, hardcoded-color scan, hardcoded-dimensions scan, block-attribute-token enforcement, and duplicate-template scan.
+- `build-index.py` — regenerates `INDEX.md`, the auto-generated single-file project map.
+- `list-tokens.py` — prints every design token in `theme.json`.
+- `list-templates.py` — prints every template alongside the URL pattern it handles.
+- `validate-theme-json.py` — verifies every block name in `theme.json` against the Gutenberg and WooCommerce sources.
+- `clone.py` — cross-platform script to copy and rename the theme for a new project.
+
+### Documentation
+
+- `README.md`, `INDEX.md` (auto-generated), `SYSTEM-PROMPT.md` (paste-in for any LLM), `AGENTS.md` (full constraints + workflow recipes).
+- Long-form docs (Architecture, Project Structure, Design Tokens, Recipes, Anti-Patterns, Block Reference, Templates, WooCommerce Integration, Style Variations, Working with LLMs, Tooling, Contributing, FAQ) live in the [project wiki](https://github.com/RegionallyFamous/Cog/wiki).
+- `_examples/` stubs for new patterns, style variations, and templates.
+
+### Theme support
+
+- `appearanceTools: true`, `useRootPaddingAwareAlignments: true`, `defaultPalette: false`, `defaultGradients: false`, `defaultDuotone: false`, `defaultFontSizes: false`.
+- `add_theme_support` for `post-formats` and full `html5` (`comment-list`, `comment-form`, `search-form`, `gallery`, `caption`, `style`, `script`, `navigation-widgets`).
+
+### Requirements
+
+- WordPress 6.8 or higher
+- PHP 8.2 or higher
+- WooCommerce 10.0 or higher (for the canonical `page-cart` and `page-checkout` template slugs)