Skip to content

Structure engine (phase 1): named macrostructures + archetype catalog + diversification - #40

Merged
codeswithroh merged 1 commit into
mainfrom
feat/structure-engine-phase1
Jul 23, 2026
Merged

Structure engine (phase 1): named macrostructures + archetype catalog + diversification#40
codeswithroh merged 1 commit into
mainfrom
feat/structure-engine-phase1

Conversation

@codeswithroh

Copy link
Copy Markdown
Owner

Background — studied Hallmark

Studied Nutlope/hallmark (15.7k★, by Together AI), the strongest anti-slop design skill in the field, end to end — its 558-line router SKILL.md, ~90-file reference tree, 50-archetype component cookbook, 58-gate slop test, and token architecture.

Its core mechanism is a combinatorial catalog of named page shapes + component archetypes with stable IDs, plus a project-memory diversification engine that forces each build to differ structurally from the last. That's the thing we didn't have — and it closes our single biggest gap.

The gap this closes

tastemaker already varies color per project (the palette generator + contrast contract). But our structure was monocultured: every landing page reached for the same hero → 3-feature-cards → CTA → footer rhythm. That's the strongest "an AI built this" tell at the page level, and it survives a perfect palette — the deepest unaddressed part of the #9 monoculture concern. Color varying while structure repeats still reads as two color-swaps of one template.

What this does — and what it deliberately keeps

Grafts Hallmark's structural machinery onto our foundation while keeping the two axes where we already beat Hallmark: the per-project generated palette + contrast contract, and the real-asset pipeline (Hallmark is typography-only with placeholders). So the archetypes here are asset-forward — real mockups/charts/photos/illustrations, not typography-only parts.

New reference files:

  • references/macrostructures.md — 12 named whole-page shapes (Feature Stack, Editorial Index, Long-Scroll Narrative, Bento Showcase, Stat-Led, Gallery Grid, Product Demo, Split Diptych, Conversational FAQ, Manifesto, Catalogue, Poster Fold) with mood affinity + an honesty rule binding proof-led shapes.
  • references/component-catalog.md — named archetypes with stable IDs + variation knobs (Nav N1-N7, Hero H1-H6, Feature F1-F7, Proof P1-P4, CTA C1-C4, Footer Ft1-Ft6, Section-head S1-S4), per-mood routing, cross-cutting rules (no fake chrome, one icon family, banned eyebrow-left head).
  • references/diversification.md — the project-memory engine: .tastemaker/log.json schema, the rotation rule (macrostructure/nav/footer/hero each differ from last build; change a knob on reuse), the "state it out loud" accountability step, the CSS build stamp. Palette is explicitly exempt (already varies by generation) — so our diversification is purely structural, a simplification our generator earns vs Hallmark's multi-axis theme rotation.

Wiring: SKILL.md gains Step 2.5 (pick structure + diversify); Step 0 reads the log, Step 4 writes the stamp + log entry; reference table updated. App-shell screens explicitly skip this (their shape is the sidebar+topbar frame). style-lock-format.md gains a Structure section; anti-slop-checklist.md gains two structural-variety gates; component-patterns.md's Landing section is cross-linked as the finer-grained guidance inside a macrostructure.

Phased plan (this is phase 1)

  • Phase 1 (this PR): structural-variety engine.
  • Phase 2 (next): upgrade the prose anti-slop checklist into a numbered, mood-scoped slop-gate list + a pre-emit self-critique pass.
  • Phase 3: study (extract design DNA from a URL/screenshot) and audit verbs.

Test plan

  • All cross-references between new + existing files resolve (grep check)
  • Fence balance and heading structure verified in all three new files
  • SKILL.md step order reads 0 → 1 → 2 → 2.5 → 3 → 4 → 5
  • No stray "preset" mentions introduced
  • Kept our generator + asset pipeline intact — this is additive structural machinery, no regression to color or assets

🤖 Generated with Claude Code

… + diversification

Studied Hallmark (github.com/Nutlope/hallmark), the strongest anti-slop
design skill in the field, to find what it does that we don't. Its core
mechanism is a combinatorial catalog of named page shapes + component
archetypes with stable IDs, plus a project-memory diversification engine
that forces each build to differ structurally from the last. That closes
our single biggest gap: tastemaker already varies *color* per project
(the palette generator), but our *structure* was monocultured — every
landing page reached for the same hero -> 3-feature-cards -> CTA ->
footer rhythm, which is the strongest "an AI built this" tell at the page
level and survives a perfect palette. It's the deepest unaddressed part
of the #9 monoculture concern.

This grafts Hallmark's structural machinery onto our foundation while
keeping the two axes where we already beat Hallmark (per-project
generated palette + contrast contract, and the real-asset pipeline
Hallmark lacks — it's typography-only with placeholders).

New reference files:
- macrostructures.md: 12 named whole-page shapes (Feature Stack,
  Editorial Index, Long-Scroll Narrative, Bento Showcase, Stat-Led,
  Gallery Grid, Product Demo, Split Diptych, Conversational FAQ,
  Manifesto, Catalogue, Poster Fold) with mood affinity and an honesty
  rule binding proof-led shapes.
- component-catalog.md: named archetypes with stable IDs + variation
  knobs — Nav N1-N7, Hero H1-H6, Feature F1-F7, Proof P1-P4, CTA C1-C4,
  Footer Ft1-Ft6, Section-head S1-S4 — built asset-forward (real
  mockups/charts/photos/illustrations, not typography-only) to match our
  show-don't-tell identity, plus per-mood routing tables and cross-cutting
  rules (no fake chrome, one icon family, banned eyebrow-left head).
- diversification.md: the project-memory engine — .tastemaker/log.json
  schema, the rotation rule (macrostructure/nav/footer/hero each differ
  from the last build; change a knob if you reuse an archetype), the
  "state it out loud" accountability step, and the CSS build stamp.
  Notes explicitly that palette is exempt (already varies by generation),
  so our diversification is purely structural — a simplification our
  generator earns vs Hallmark's multi-axis theme rotation.

Wiring:
- SKILL.md: new Step 2.5 (pick macrostructure + archetypes, diversify
  against project memory) between style and assets; Step 0 reads
  log.json; Step 4 writes the stamp + log entry; reference table + new
  files added. App shell screens explicitly skip this step (their shape
  is the sidebar+topbar frame in component-patterns.md).
- style-lock-format.md: new Structure section recording the project's
  macrostructure + shared chrome + per-page archetypes.
- anti-slop-checklist.md: two structural-variety gates (not the generic
  template + differs from last build; no generic-template chrome tells).
- component-patterns.md: Landing section cross-linked to the new
  structural layer as the finer-grained guidance inside a macrostructure.

This is phase 1 of bringing tastemaker to Hallmark's caliber. Later
phases (separate PRs): a numbered/genre-scoped slop-gate list +
pre-emit self-critique, and study/audit verbs.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@codeswithroh
codeswithroh merged commit f2abe42 into main Jul 23, 2026
@codeswithroh
codeswithroh deleted the feat/structure-engine-phase1 branch July 23, 2026 04:17
codeswithroh added a commit that referenced this pull request Jul 26, 2026
Resolves #54. Four real writeups sourced from actual prior work, not invented:

- section-spacing-measurement.md — the make.design DOM-introspection measurement behind #48
- hallmark-architecture-study.md — the structural-gap study behind #40/#41/#42, including an honest account of where tastemaker already led Hallmark and where it didn't
- contrast-as-authored-vs-as-used.md — the multi-reviewer-converged finding behind #16/#18's contrast contract
- non-latin-typography.md — the Pretendard/Hangul research (three independent sources) behind #39

Each links the PR that actually shipped the fix, the same honesty standard the site changelog already holds to. Linked from the README (new Research section + anchor nav) and from research/README.md as an index.

Also fixes em-dash house-style violations introduced in #71's CHANGELOG.md and site/changelog.html — README/CONTRIBUTING/site content stays em-dash-free per this project's standing convention; caught on review before merge, not after.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant