@3xhaust/oh-my-design 0.16.1

package/core/theory/craft.md

@@ -0,0 +1,270 @@
+# Craft — decision material
+
+These are the decisions that separate work that looks designed from work that looks
+generated. None of them appear in textbooks as principles; they are accumulated from
+practitioners watching what fails and adjusting. Every entry is a condition → choice →
+reason triple, verified against real practice.
+
+---
+
+## Shadows: layered and coloured, never single-heavy
+
+A single dense shadow — `box-shadow: 0 4px 20px rgba(0,0,0,0.4)` — reads as generated.
+It is the shadow that appears when someone types "add a box shadow" and accepts the
+default. It looks heavy, uniform, and unnatural because nothing in the physical world casts
+light that way.
+
+Natural shadow results from at least two light interactions: the ambient light that fills
+a space with soft diffuse shadow, and the direct light that casts a sharp shadow close
+beneath the object. Adam Wathan and Steve Schoger (*Refactoring UI*, 2018) document this
+as the two-shadow system: a small, tight shadow directly beneath the element (sharp, low
+opacity, small blur radius) and a larger, softer shadow extending further (large blur,
+very low opacity). The two together read as physically plausible in a way a single shadow
+cannot.
+
+The values: a card at moderate elevation might use
+`box-shadow: 0 1px 3px rgba(0,0,0,0.12), 0 4px 16px rgba(0,0,0,0.08)`. The first shadow
+places the card; the second lifts it. Combined opacity stays low — the visual weight
+is distributed across both.
+
+**Coloured shadows** extend the system further. A shadow cast beneath a blue button does
+not need to be grey — it can be a dark desaturated blue. This is how physical coloured
+objects cast coloured shadows (ambient lighting takes on the hue of the emitting surface).
+A coloured shadow reads as considered rather than default, and it ties the shadow to the
+element's own colour system, making the depth feel coherent.
+
+Condition → choice → reason: when adding elevation, compose two shadows at low opacity
+rather than one at high opacity. When the element has a distinct brand colour, tint the
+shadow toward that hue at 20–30% saturation.
+
+---
+
+## Borders vs background contrast: the separation decision
+
+Borders are not the only way to separate things. They are the heaviest way, and they add
+the most noise.
+
+Three alternatives work better in most situations:
+
+**Background contrast**: adjacent elements with slightly different background colours read
+as separate without a line between them. A sidebar at `#F7F7F7` and a content area at
+`#FFFFFF` need no border — the contrast between them creates the separation. This is the
+technique behind most modern sidebars, navigation panels, and card layouts where the
+"border" is actually a 5% luminance difference. Wathan and Schoger (*Refactoring UI*)
+name this explicitly: "Giving adjacent elements slightly different background colors is
+usually all you need to create distinction between them."
+
+**Space as separator**: if two elements have enough gap between them, the negative space
+reads as the boundary. A group of form fields at 24px internal gap and 48px between
+sections needs no horizontal rule — the spacing hierarchy is the divider.
+
+**Subtle box-shadow as outline**: `box-shadow: 0 0 0 1px rgba(0,0,0,0.06)` creates a
+visible border-weight outline without the hard, opaque line of `border: 1px solid`. At low
+opacity, this reads as surface definition rather than containment — appropriate for cards
+on white backgrounds where a hard border would create visual noise.
+
+The rule: use a border when none of these three alternatives produce sufficient separation.
+In practice, this means borders are reserved for form inputs (where the border communicates
+interactivity, not just separation), data tables (where the row-column structure requires
+explicit lines for alignment), and code blocks.
+
+---
+
+## Text hierarchy: opacity over grey
+
+When designing on a coloured background — a dark surface, a brand-coloured header, a card
+with a coloured fill — secondary text is often set in a lighter grey to signal its lower
+importance. This fails on coloured backgrounds: a fixed grey hex sits at the wrong
+luminance relative to the background, either too light (insufficient contrast) or too dark
+(indistinguishable from primary text).
+
+The correct technique is opacity on white (or the background-adjacent colour), not a
+separate grey value. Primary text: white at 87–90% opacity. Secondary text: white at
+55–65% opacity. Tertiary / disabled: white at 35–40% opacity. These values come from
+Material Design's dark theme specification and have been independently confirmed as
+the correct perceptual steps.
+
+The reason opacity outperforms fixed hex on coloured surfaces: opacity lets the background
+colour bleed through. The secondary text picks up the surface hue, which makes it feel
+native to the surface rather than pasted on. A fixed grey on a dark blue card looks like
+a grey text on a blue background; an 60% opacity white on a dark blue card looks like
+dim text that belongs on that card.
+
+On light backgrounds, the same logic applies in reverse: use black (or the text colour)
+at different opacity levels for hierarchy, rather than separate grey tokens. The cascade
+reads as a single family at different weights of presence, not as multiple colours
+competing.
+
+---
+
+## Optical alignment: why mathematical centre is wrong
+
+Centering by coordinate is not the same as centering by perception. The eye processes
+visual weight, not coordinates; a perfectly centred element that carries more visual weight
+at the top will appear to sit too low.
+
+**The most common violation**: icons inside circular or square containers. A triangle
+icon centred by coordinate at the geometric centre of its container appears to float too
+high, because the triangle carries visual mass at its base and open space at its peak.
+Correct optical alignment moves the icon 1–2px downward from coordinate centre.
+
+**The second-most common violation**: icons beside text. An icon at 16px placed alongside
+16px text is not optically aligned — the icon's visual centre and the text's cap height
+are at different heights. The correct alignment is not to align the icon's bounding box
+midpoint to the text's bounding box midpoint; it is to align the icon's optical centre
+to the text's cap height. This often requires the icon to be 1–2px lower than a strict
+middle-align would place it. Rauno Freiberg's web interface guidelines (interfaces.rauno.me)
+note that when text and icons sit side by side, adjustment of weight, size, or position is
+required so they don't clash visually.
+
+**The third violation**: padding on buttons. A button with 16px padding top and bottom
+appears to sit low if the label is a capital-heavy word, because the ascenders occupy
+optical space that descenders do not. Adding 1px of extra top padding corrects it
+optically while maintaining the stated 16px value in both directions.
+
+Condition → choice → reason: when an element "looks off" despite correct coordinate
+values, the issue is optical weight distribution. Adjust by eye in 1px increments until
+the perception matches the intent, then document the deviation.
+
+---
+
+## Optical balance vs mathematical symmetry
+
+A symmetrical layout is not always a balanced one. Mathematical symmetry places elements
+at equal distances from a central axis; optical balance places them at positions where
+they carry equal visual weight.
+
+The most common asymmetry that reads as balance: a heavy text block on one side paired
+with a large open area on the other, because white space carries visual weight. Müller-
+Brockmann's grid work (and its later formalisation in Josef Albers' compositional studies)
+establishes that a large empty area "pushes back" against a dense content block — the
+result is tension and balance, not imbalance.
+
+The practical consequence: a design that looks "too light on the right" may not need more
+content on the right. It may need the existing content moved slightly left, or a single
+visual anchor (a horizontal rule, a colour block, a differently weighted element) on the
+right that resolves the imbalance without filling the space.
+
+Symmetry is a statement. Perfect bilateral symmetry says "this is formal and restrained."
+Near-symmetry with deliberate asymmetric elements says "this is considered." Accidental
+asymmetry — elements placed symmetrically by coordinate that read as unbalanced because
+of optical weight — says "nobody checked."
+
+---
+
+## Hover states: compound changes over brightness alone
+
+Changing brightness on hover — lighter on hover of a dark element, darker on hover of a
+light one — is the default hover behavior and produces the least interesting result.
+It communicates "interactive" but nothing else. Compound hover changes communicate more.
+
+A hover state can change multiple properties simultaneously to produce a richer signal:
+
+- **Background + shadow**: the background lightens slightly and a subtle shadow appears,
+  suggesting the element is rising off the surface to meet the cursor. This communicates
+  elevation change rather than just colour change.
+
+- **Colour + underline reveal**: for text links, a colour shift combined with an underline
+  appearing on hover communicates "this is a link" more reliably than either signal alone.
+  The underline is the semantic signal; the colour shift is the visual confirmation.
+
+- **Scale + shadow**: a slight scale increase (`transform: scale(1.02)`) on a card combined
+  with a shadow increase communicates physical lift — the card rises. Scale alone without
+  shadow reads as zoom; shadow alone without scale reads as flat highlighting.
+
+Rauno Freiberg's guidelines specify that font weight should remain consistent on hover
+or selected states to prevent layout shifts — a `font-weight` change on hover causes
+surrounding text to reflow, which is distracting even at the character level. Use `bold`
+for initial state or accept that the hover state cannot add weight.
+
+The constraint from `prefers-reduced-motion`: all hover transitions must be instant (or
+very short) when `prefers-reduced-motion: reduce` is active. A compound hover transition
+that takes 200ms looks fine; the same 200ms transition replaying on every link in a dense
+page layout is distracting. Scale transformations in particular should be removed or
+reduced to zero duration under `prefers-reduced-motion`.
+
+---
+
+## 60fps-safe properties
+
+Not all CSS properties are created equal for animation. The browser rendering pipeline
+processes properties in three stages: layout (positioning, sizing), paint (colour,
+background, shadow), and composite (transform, opacity). Only composite-stage properties
+can be offloaded to the GPU and animated without touching the layout or paint pipeline.
+
+**Safe for animation** (composite only — 60fps on all reasonable hardware):
+- `transform: translate()`, `rotate()`, `scale()`
+- `opacity`
+
+**Unsafe for animation** (trigger layout or paint — cause jank on mid-range devices):
+- `width`, `height`, `top`, `left`, `bottom`, `right`
+- `padding`, `margin`
+- `border-width`
+- `background-color` (triggers paint, not layout — less severe but not free)
+- `box-shadow` (triggers paint on every frame)
+
+The practical constraint for design: if the visual effect requires animating a property
+not on the safe list, re-examine whether the effect can be achieved through transform and
+opacity instead. A "growing border" on hover can be achieved with a `box-shadow` inset of
+0 opacity transitioning to opacity 1 — or better, with a `transform: scaleX()` on a
+pseudo-element. A "sliding in from the side" panel should use `transform: translateX()`,
+not `left: -100%` to `left: 0`. The design constraints are the engineering constraints.
+
+---
+
+## The "design is boring" checklist
+
+When a design feels flat or unresolved and you do not know what to change, this checklist
+provides the diagnostic. Each item identifies a specific deficiency and its correction.
+
+**1. Contrast scale is too narrow.** All text is at similar sizes. The solution is to make
+the most important element dramatically larger — not 20% larger, but 2–3× larger. Dramatic
+scale contrast reads as intentional hierarchy; mild scale difference reads as inconsistency.
+
+**2. Everything is centred.** Centring is emphasis. When everything is centred, emphasis
+is absent. Left-align body content, reserve centring for single-line headlines and
+isolated call-out elements.
+
+**3. The colour palette has no accent.** All colours are muted or neutral — there is
+nothing with visual energy. Add one high-saturation or high-contrast element in the accent
+role, even briefly, and the composition becomes legible.
+
+**4. Alignment axes are too consistent.** When every element aligns on the same left edge
+and the same grid column, the design reads as orderly but static. One intentional
+misalignment — a large decorative element that bleeds past the grid, a pull quote indented
+from the main measure — creates movement. But only one: two misalignments become chaos.
+
+**5. Weight ladder is too flat.** Text throughout the design uses the same weight. The
+hierarchy exists only through size. Add weight contrast: the primary content at
+`font-weight: 600`, secondary at 400, tertiary at 400 and reduced opacity. The weight
+ladder is the cheapest hierarchy tool available.
+
+**6. There is no breathing room.** Padding and margins are too conservative. The
+conventional instinct is to pack content because packed content "shows more value." Empty
+space reads as confidence; packed space reads as uncertainty. Double the padding on the
+most important element and observe whether it reads as more important, not less.
+
+**7. No element is unexpected.** Everything is where the user expects it to be, at the
+scale they expect it. Introduce one element that is larger, different, or placed
+differently than its role would suggest. This is the Von Restorff mechanism: the
+unexpected element is what gets remembered.
+
+---
+
+## Sources
+
+- Wathan & Schoger, *Refactoring UI* (2018 / refactoringui.com) — two-shadow system,
+  borders vs background contrast, colour hierarchy on coloured backgrounds, two-weight
+  system for text hierarchy
+- Rauno Freiberg, Web Interface Guidelines (interfaces.rauno.me) — optical alignment of
+  icons and text, hover weight consistency, animation duration ceiling, tabular figures
+- Material Design 3 (2023) — white-opacity text hierarchy on dark surfaces (87%/60%/38%),
+  GPU-composited animation properties
+- Müller-Brockmann, *Grid Systems in Graphic Design* (1981) — optical balance and the
+  visual weight of negative space
+- Albers, *Interaction of Color* (1963) — visual weight, optical perception of spatial
+  relationships, the inadequacy of coordinate-based alignment
+- von Restorff, "Über die Wirkung von Bereichsbildungen im Spurenfeld" (1933) — the
+  isolation effect and why one unexpected element produces memory while many produce none
+- Google Chrome Developers, "Stick to Compositor-Only Properties and Manage Layer Count"
+  (developers.google.com) — composite-only animation properties, paint and layout costs

package/core/theory/expressive.md

@@ -0,0 +1,213 @@
+# Expressive — decision material
+
+An award-winning site is not one that does more. It is one where every choice points at the same thing. Awwwards puts the scoring on record: Design 40%, Usability 30%, Creativity 20%, Content 10% (awwwards.com/about-evaluation). The arithmetic is the argument. Creativity — the axis where spectacular effects live — accounts for one-fifth of the score. Usability accounts for thirty percent. A site that trades navigability for spectacle is betting against the judges' own rubric. The sites that win do so on Design and Usability combined, which means art direction that holds up under use, not technique that demands admiration.
+
+This file is decision material for the register axis. It is not a catalogue of cool things to do. It is a condition→choice→reason map for when expressive technique earns its place and when it does not.
+
+---
+
+## The register decision
+
+Every brief implies a register. The register is not the visual style — it is the intensity of the directed experience. Three positions on the axis:
+
+**quiet**: The interface recedes. The user's work or content is the event. Dashboards, documentation, tools, reading-first products. Motion is near-zero. Typography is functional. Restraint is not timidity; it is the correct reading of what the user came to do.
+
+**confident**: A position is visible but the interface does not perform. Brand sites, editorial products, most portfolio work. One thing is done well — a considered type scale, a deliberate palette — and nothing else competes. This is where most good work lives.
+
+**showpiece**: The interface is the event. Brand campaign microsites, agency portfolios, product launches with a single CTA, experiential landing pages. The user came partly to experience being here. Awwwards SOTD, FWA, GDWEB — these are showpiece contexts. The register commits to one signature moment and builds everything toward it.
+
+The error is applying showpiece technique to quiet or confident contexts. A dashboard with split-text entrances is not ambitious; it is misread. The thirty-percent Usability weight does not become a thirty-percent weight only when the judges disagree with your taste — it applies regardless of intent. Usability 30% is the reason showpiece technique must still serve navigation and clarity, not just aesthetic ambition.
+
+---
+
+## The anatomy of award-level sites
+
+### A concept-bearing line can replace an image
+
+On some showpiece sites, a short actual headline becomes the visual event. The face and
+weight must carry the concept; size alone is not a concept. The pre-structure typography
+proof tests target-language glyphs, loading, fallback, wrapping, and the availability of
+secondary hierarchy and CTA at desktop and mobile.
+
+Size derives from the real copy and container. `clamp()`, container queries, media queries,
+and discrete steps are all valid when specimens justify them. A moderate heading can pass;
+huge Hangul can also pass when its syllable rhythm is concept-bearing and proof-clean. A
+long heavy line that becomes a clipped mobile wall fails even if one desktop render works.
+
+### Scroll is the narrative axis
+
+On a showpiece site, sections are not containers — they are scenes. The order of scroll is the order of a story: exposition, complication, turn, resolution. If the sections could be reordered without loss, there is no scroll narrative, only content in a column.
+
+The structural implication: the first scene commits to the register, the middle scenes develop it, and the footer scene closes it. A footer that reverts to default template styling breaks the narrative as certainly as a film that ends with stock footage.
+
+CSS scroll-driven animations (the `animation-timeline: scroll()` and `view()` properties, now available in Chromium and WebKit as of 2024) enable scroll-linked motion without JavaScript. The correct fallback for unsupported browsers is the static layout — which must be designed to stand without the motion. An experience that is illegible when still is not a scroll narrative; it is content that depends on JavaScript to exist.
+
+### The first three seconds declare the register
+
+A loader or entrance animation on a showpiece site is not a technical necessity — it is the opening sentence. It tells the user: this is what kind of experience you are in. A loader that runs longer than the asset load time is a loader that is costing more than it earns. The outer bound is three seconds; under one second is the performance target. Beyond that, a fast site is made to feel slow, and the Usability score suffers before the user has seen a single thing.
+
+What the entrance must do in those seconds: commit the palette, declare the type register, establish the motion vocabulary. A loader that is only a spinner followed by a page reveal has wasted the three seconds it consumed.
+
+### The concept must survive to the footer
+
+A showpiece site that loses its nerve in the footer — reverting to small-print-grey, default columns, four generic links — reveals that the expressive register was applied to the hero and nowhere else. Applied design covers the whole surface. The footer is a scene. It may be quieter than the hero, but it is not absent.
+
+---
+
+## Slop-free is not the same as distinctive
+
+Passing every slop gate proves the absence of a known defect. It does not prove the presence of a design. A layout can be measurably clean — correct contrast, no triple-radius, no gradient-mesh cliché, one primary action — and still read as AI-made, because the composition itself is the most predictable arrangement of its parts. Distinction is a positive property the gates cannot supply; it has to be committed on purpose.
+
+The AI-made feel is not one slop pattern. It is the sum of safe defaults: symmetric balance, boxed regions, evenly-weighted columns, and the single most common arrangement for the content type. A skeptical viewer reads it in one second — "a model produced the reasonable layout" — and that read is the failure, independent of any individual clean metric.
+
+### Template tells (clean, but generic)
+
+Each is a layout that survives the slop scan and still announces a template. Treat a match as a distinction failure to break, not a pass.
+
+- **Symmetric hero split**: oversized headline on the left, a bordered panel or card on the right, balanced masses. Two competing primary masses is the usual side effect — the eye cannot find the one thing that matters first.
+- **Triple feature-cards with arrows**: three equal-weight boxes (SIGNAL → SYSTEM → PROOF, or any A → B → C) joined by arrows. The single most templated way to show a process; recognizable as generated at a glance.
+- **Trend-decoration as identity**: an offset drop-shadow, a glassmorphism blur, or a gradient border used as *the* idea rather than in service of one. A dated trend applied evenly is not art direction.
+- **Boxed everything**: every region gets a border, a radius, and equal padding, so nothing dominates and the grid never breaks. Uniform containment reads as a system, not a composition.
+- **Unused real material**: the brief supplies photographs, slides, a portrait, or data, and the layout still leads with text-in-boxes. Authentic material left out of the composition is the clearest tell that the layout was reasoned in the abstract.
+
+### The one-risk requirement
+
+A distinctive composition commits at least one genuine risk a template would not take, grounded in the concept and never in decoration: a deliberate asymmetry that directs the eye to one mass; a scale or weight contrast large enough to read as a decision, not a default; a grid break at the one moment that matters; or the real supplied material (image, portrait, slide, dataset) made structural rather than illustrative. One committed risk beats five safe refinements. If a candidate reads as "the reasonable layout," it has not earned the register — name the template it resembles and depart from it once, on purpose.
+
+### The AI-SaaS landing tells (the specific template to break)
+
+The most common generic result is the AI-SaaS landing page. Every item below is a tell to avoid, not a default to reach for — a design that matches the checklist reads as machine-made in one second regardless of polish.
+
+- **Layout**: a centered hero (big one-line headline, short subhead, prompt box), a logo wall, then every section as a 3-column card grid with a small eyebrow label ("Features", "Use cases", "Testimonials"); sections divided only by gradient blobs; everything floating centered with left/right balance but no tension; more whitespace than the content earns; the same card component repeated down the page.
+- **Fabricated proof**: a pretty UI mockup instead of a real product screenshot, with invented dashboard data and cliché figures (98%, 10x, 24/7). This is also a fabrication violation — never ship invented numbers or a fake product screen (see `graphics/placeholder-policy.md`).
+- **Type**: a safe SaaS sans (Inter/Geist/Satoshi feel), an over-formal size hierarchy, grey body, a slightly faded subhead, one word (usually "AI") set in a purple gradient, keywords in pills, every sentence the same length — pretty type with no brand voice.
+- **Copy**: the phrases in `theory/voice.md` and the `omd text-slop` scanner — "Supercharge your workflow", "Work smarter not harder", "Unlock your creativity", "AI-powered", "10x", "No code required", "The future of", "Next-generation", "let AI do the heavy lifting", "effortless".
+- **UX (product surfaces)**: the tool suggests before the user acts; empty states full of "Try asking…" chips; a bigger Regenerate than Edit; "shorter / longer / change tone" buttons; thumbs up/down and "Was this helpful?"; "Option 1, 2, 3" instead of one committed answer; "Analyzing… / Generating…" theatre. These make the product feel like a demo of AI, not a tool that solves a problem.
+
+The underlying failure — why designers call it "AI slop" — is mood before function, no brand specificity, seen-it-before, unaudited details, visual density high but information density low, no tension or rhythm or contrast, no human life, too average, too safe. The fix is never more effects; it is one concrete, brand-specific, evidence-grounded decision a template would not make.
+
+---
+
+## Technique catalogue
+
+Each entry names the condition under which the technique earns its place and the condition under which it does not.
+
+### Split-text entrance (character- or word-level stagger)
+
+**Condition for use**: The hero type is the primary visual event and the words are part of the concept — something is being said, not just displayed. The split reveals meaning progressively: each word or line lands with intent.
+
+**Condition against**: Body copy, UI labels, secondary headings, any text the user will need to skim. Split-text on body copy turns reading into waiting. It is the most common technique deployed too broadly. GSAP SplitText and SplitType both require JavaScript; the fallback state (no JS, or reduced-motion) must show the complete text, not an empty space.
+
+**Implementation constraint**: Stagger between siblings at 40–80ms. Beyond 80ms the entrance becomes a waterfall the user watches rather than reads.
+
+### CSS scroll-driven animations / IntersectionObserver reveals
+
+**Condition for use**: The content is a scroll narrative — sections have a sequential logic, and the reveal of each section reinforces the sequence. The animation is `transform` and `opacity` only; nothing that touches layout.
+
+**Condition against**: Product UI that the user came to operate. Navigation elements. Any element the user needs to see immediately on scroll — a reveal that delays reading is a usability failure regardless of how well-timed it is.
+
+**Implementation**: CSS scroll-driven animations (`animation-timeline: scroll()` / `view()`) are the first choice — they run off the main thread and require no JavaScript. IntersectionObserver is the fallback for broader browser support. The static layout must be complete and functional without the motion layer.
+
+### Viewport-filling marquee
+
+**Condition for use**: The marquee carries a message that is part of the concept — a repeated claim, a rhythmic brand phrase, a counter. The motion is continuous and low-velocity; it does not compete with adjacent interactive elements.
+
+**Condition against**: Navigation areas, any context where the user is reading or interacting with nearby content. A marquee adjacent to a form field splits attention between peripheral motion and the focal task — vestibular disruption for users with motion sensitivity, even when `prefers-reduced-motion` is honoured. In reduced-motion contexts, the marquee must stop.
+
+### Custom cursor (desktop, pointer media query)
+
+**Condition for use**: The cursor reinforces the concept in a way no other element can — it follows the user's intent, so it is always in the interaction zone. Effective on portfolio and agency sites where the cursor is part of the brand vocabulary (Awwwards, awwwards.com/customize-your-mouse-cursor).
+
+**Condition against**: Touch devices (the cursor does not exist). Any context where the interactive affordance of links and buttons needs to be clear without hover cues — custom cursors routinely break the expected `cursor: pointer` signal. Must be scoped with `@media (pointer: fine)` so it never activates on touch. On mobile it is invisible; its absence must not degrade the layout.
+
+### Image hover distortion / filter
+
+**Condition for use**: A gallery or portfolio grid where the hover state deepens engagement with a piece before the user clicks. The distortion (WebGL ripple, CSS filter shift, GSAP hover tween) must complete in under 150ms for hover onset and under 200ms to settle. Anything slower reads as broken.
+
+**Condition against**: Product images where accuracy matters (e-commerce, documentation). Navigation thumbnails where the user is trying to read text.
+
+### Grain / noise texture
+
+**Condition for use**: Flat backgrounds or smooth gradients that read as too digital — noise adds the tactile quality that solid fills lack. The CSS-Tricks SVG filter technique (an `feTurbulence` filter composited at low opacity over a background) adds texture without weight. Particularly effective over mesh gradients, where it reduces banding.
+
+**Condition against**: Over photography or video (redundant). On text (degrades legibility at small sizes). At high opacity on any element (reads as low-resolution encoding, not design).
+
+### Asymmetric / diagonal grid
+
+**Condition for use**: The concept requires tension — an editorial feeling where elements do not settle into comfortable columns. One diagonal or off-grid element is a decision; a page full of diagonal elements is entropy.
+
+**Condition against**: Data-heavy layouts where scanability is the primary requirement. Tables, forms, anything the user reads in order.
+
+### Section colour inversion (dark ↔ light transition)
+
+**Condition for use**: The scroll narrative has a turn — a moment where the register shifts to mark a conceptual pivot. The inversion makes the change visible and felt, not just read. One inversion per page is usually correct; more than one is a rhythm, not a pivot.
+
+**Condition against**: Arbitrary decoration. The inversion must correspond to a narrative event, not to a desire for visual variety. When the colour switches back without a corresponding conceptual return, the technique has been used as decoration and should be removed.
+
+### Sticky stage / scene sequencing
+
+**Condition for use**: A multi-scene showpiece where each scene requires the user's full attention before advancing — a product demo, a feature walk-through with animated states, a narrative with distinct chapters. The stage (`position: sticky`) pins the viewport while scroll advances the timeline inside the scene.
+
+**Condition against**: Sites where the user is goal-oriented and is scrolling to find something specific. Sticky stages are navigation debt — the user cannot scroll past to scan; they must watch the scene play. If they have seen it before, it is friction. If there is any chance of return visits, the stage needs an explicit skip or fast-forward affordance.
+
+### Editorial number / index labels (01, 02, 03)
+
+**Condition for use**: The content has a genuine sequence — steps, chapters, items in an ordered argument. The large number (set at display scale, often 10–15% opacity as a background element) reinforces the ordered reading without becoming the dominant visual.
+
+**Condition against**: Fake sequences — content that is enumerated to look like it has order but does not. Numerical labels that carry no sequential meaning are decoration, and decoration at display scale is noise.
+
+### Blend-mode typography
+
+**Condition for use**: Text that must maintain legibility and contrast across a moving or textured background — `mix-blend-mode: difference` inverts the pixel values at each point of contact, guaranteeing contrast regardless of what is behind the type. Effective on full-bleed images or video backgrounds where fixed colour choices will fail in some regions.
+
+**Condition against**: Static backgrounds where the contrast can be calculated and set directly — `difference` on a static background produces a predictable result that could be a fixed colour choice, but with more browser overhead. Not appropriate for body copy (the visual complexity of difference blending at small sizes degrades legibility).
+
+---
+
+## The restraint clause
+
+The techniques above are a catalogue, not a checklist. A showpiece site uses two or three of them, chosen because the concept requires them, and executes each one with precision. A site that uses eight of them is an effects catalogue, not a design. It is what the Awwwards guide calls "randomness without microinteractions" — stimulation without meaning.
+
+The selection discipline: before adding any technique, ask whether the concept — the governing metaphor — would do this. A concept framed as "a deep-sea research vessel" would animate precisely, with technical legibility, and would never distort images playfully. The same concept would not use a pastel grain texture. If the technique does not follow from the concept, it is decoration.
+
+**Performance is not a category below craft** — it is part of Usability, which is 30% of the score. Animating only `transform` and `opacity`, honouring `prefers-reduced-motion`, and staying within 60fps on mid-range hardware are not concessions to accessibility; they are the conditions under which the expressive register earns its score. An animation that causes layout jank has failed the Usability criterion. A motion that does not honour `prefers-reduced-motion: reduce` has failed both Usability and Accessibility.
+
+---
+
+## Korean showpiece typography
+
+GDWEB (gdweb.co.kr), operating since 2005, is the leading Korean web design award. Winning categories skew toward agency brand sites and campaign microsites — seasonal brand launches, product campaign pages, experiential brand activations — rather than application UI. The showpiece register is the expected register on GDWEB, not the exceptional one. This means the baseline for expressive work in the Korean market is higher; mid-level expressive execution that would earn attention internationally passes unnoticed against the GDWEB field.
+
+Hangul syllable blocks create a different visible rhythm from Latin letters, but they do not
+imply a fixed size or tracking limit. Inspect the chosen face's counters, stroke density,
+punctuation, mixed Latin/numerals, and wrapping with actual Korean copy. Word-based and
+character-based Hangul breaking are both documented practices; choose one from the task and
+verify it in the intended container. Huge Hangul is justified when the words are short and
+concept-bearing and the face/weight remains clean at both proof viewports. It fails when a
+heavy long sentence wraps into an undifferentiated wall, clips, falls back, or removes the
+secondary message and CTA.
+
+---
+
+## Graphics recipes
+
+The background and image treatment techniques referenced in this file — grain texture,
+gradient mesh, geometric patterns, CSS illustration primitives, duotone image presets —
+are implemented as working CSS recipes in `core/graphics/`. The placeholder policy
+(grey box is a defect; typographic block, pattern fill, or generated gradient instead)
+is documented in `core/graphics/placeholder-policy.md`.
+
+## Sources
+
+- Awwwards, Evaluation System (awwwards.com/about-evaluation) — Design 40% / Usability 30% / Creativity 20% / Content 10%, confirmed from the official criteria page
+- Awwwards Academy, "Art Direction Secrets to Create Unique Web Experiences" (awwwards.com/academy) — concept as the primary variable in SOTD awards; effects as amplifiers of concept, not substitutes
+- Streza, "A Guide on Building Awwwards Worthy Websites" (medium.com, via awwwards.com search results) — one signature moment per page; microinteractions and randomness as distinguishing factors
+- MDN Web Docs, CSS scroll-driven animations (developer.mozilla.org/en-US/docs/Web/CSS/Guides/Scroll-driven_animations) — `animation-timeline: scroll()` / `view()` specification and browser support
+- WebKit, "A Guide to Scroll-Driven Animations with Just CSS" (webkit.org/blog/17101) — Safari support for scroll-driven animation spec
+- Codrops, "Custom Cursor Effects" (tympanus.net/codrops/2019/01/31/custom-cursor-effects/) — pointer media query scoping; hover zone behaviour
+- Lea Verou / CSS-Tricks, "Grainy Gradients" (css-tricks.com/grainy-gradients/) — SVG feTurbulence filter technique for noise texture; banding reduction on smooth backgrounds
+- W3C, Requirements for Hangul Text Layout and Typography (w3.org/TR/klreq/) — syllable block structure; spacing constraints and the fixed-width character cell at display scale
+- Awwwards, "Customize your mouse cursor" (awwwards.com/customize-your-mouse-cursor) — cursor as brand vocabulary on award-winning sites; pointer-fine scoping requirement
+- GDWEB Design Awards, About (gdweb.co.kr/sub/about.asp) — Korean award context, judge composition, selection categories dominated by agency and campaign microsites
+- Motion theory cross-reference: see `core/theory/motion.md` — duration windows, reduced-motion requirement, transform/opacity constraint, and the attention budget argument all apply in the showpiece register without exception
+- Motion cookbook: working implementations of every technique catalogued above (split-text, scroll-reveal, sticky scene, section inversion, marquee, magnetic hover, and more) are in `core/motion/recipes/`; easing token vocabulary is in `core/motion/easing.md`

package/core/theory/imagegen.md

@@ -0,0 +1,105 @@
+# Imagegen — image-first art direction (decision material)
+
+Adapted for OMD from the image-direction discipline in lazycodex's `frontend` skill
+(`imagegen-frontend-web`, `image-to-code`; Apache-2.0, github.com/code-yeongyu/lazycodex). This is
+an OMD-native synthesis bound to OMD's evidence, clean-room, and anti-fabrication rules — not a copy.
+
+**A generated image is a design reference, never a shipped asset.** It plays the exact role a Figma
+export or a hand mockup plays: a visual contract the build implements against. It obeys the clean-room
+boundary (`protocol/human-design-loop.md`) — you transfer layout grammar, token relationships, and
+composition decisions, not pixels. A generated mockup never ships as a page `<img>`. Shipped imagery
+still obeys `asset-sourcing`: a factual carrier (team photo, product screenshot, real person, logo)
+is NEVER AI-generated; only an abstract or atmospheric zone may ship generated imagery, and only with
+committed provenance recorded via `omd decision`.
+
+## The safety backstop makes reference-seeding safe
+
+Seed the concept drafts from the real reference board — the scout's measured principles and the
+component references it captured with `omd ref add … --selector … --blueprint --shot`, which pair
+each component's screenshot with its skin-abstracted structural grammar on one record, plus the
+committed palette/type/material. This is the composer's art-direction step, not a build step: feed
+the paired screenshots and blueprints to the image tool as multi-source references, but the builder
+never sees these reference screenshots — it implements from the generated draft. Combining
+multiple references into a NEW synthesis is the whole point, and it is safe here
+for one specific reason: `omd ref distance` still measures the SHIPPED build against every saved
+reference and nothing at or above 0.6 kinship ships. The kinship gate is the anti-laundering backstop,
+so imagegen may be seeded richly without risking a copy — the final build is gated regardless of how
+the mockup was seeded. Never seed a draft from a single reference alone and never target a specific
+reference's pixels; synthesize 2–3 references' grammar plus the project's own concept.
+
+## When image-first applies
+
+Image-first is for confident/showpiece register work where the visual composition is a first-class
+deliverable — landing pages, marketing sites, portfolios, brand/editorial pages, redesigns where the
+look is the point. For a quiet register (dashboard, docs, tool) it is usually unnecessary; the content
+is the event and a mockup adds nothing. Skip it and record why.
+
+When the host provides an image-generation capability and image-first applies, the order is
+**mandatory**:
+
+1. **Generate** 2–3 art-directed concept-draft mockups concurrently (they are independent — do not
+   serialize them), each seeded with the committed concept's palette, type register, and material
+   PLUS the scout's paired component references (screenshot + skin-abstracted blueprint from
+   `omd ref add … --shot`) and measured principles as multi-source input. One horizontal image per
+   section for a multi-section page — never one tall board
+   with unreadable text. Do not crop an old image for a detail view; regenerate that section fresh,
+   keeping the same palette/type/radius/treatment. Store drafts under `.omd/.cache/imagegen/` and
+   record their paths + the pick with `omd decision`.
+2. **Analyze** the chosen draft cleanly, not vibe-only: extract tokens, layout geometry, spacing
+   rhythm, type-scale relationships, component anatomy, interaction affordances, and each section's job.
+3. **Feed** the chosen draft into `.omd/composition.md` as the reference-fidelity direction, then build
+   against it and run `omd ref distance` as usual. If the host has no image capability, fall back to
+   the evidence-based composition path — the reference board, `theory/expressive.md`, and the CSS/SVG
+   graphics recipes — and record the fallback.
+
+Reasoning the layout in the abstract is exactly what produces the symmetric, boxed, template output
+`expressive.md` § "Slop-free is not the same as distinctive" warns about. A generated draft forces a
+concrete art direction to react to instead of a reasonable-sounding description.
+
+## Break the AI defaults (aggressively)
+
+Standard image generation and abstract layout-reasoning both collapse into the same tells. Name the
+one a draft is drifting toward and reject it:
+
+- centered dark hero with a purple/blue glow; floating meaningless blobs
+- **left-text / right-image hero** — the single most overused AI pattern; allowed only when it is
+  genuinely the strongest fit, never the default first instinct
+- generic dashboard/card spam; cards inside cards inside cards; giant rounded containers everywhere
+- weak typography hierarchy; boring default web-type energy
+- "luxury" that is only beige serif text; "creative" that is actually messy and unreadable
+- text-heavy layouts with too little imagery; over-packed sections with no breathing room
+- tiny pills, tags, and fake interface jargon used as decoration
+
+## The variation engine
+
+Commit to ONE strong option per axis and execute it consistently — do not mash everything together,
+and do not repeat one anchor down the whole page. Bias toward stronger visual concepts, but the brief
+always overrides: "clean/minimal/swiss" lowers density and variance; "editorial/creative/bold/개쩔게"
+raises them.
+
+- **Theme**: pristine light · deep dark · bold studio solid · quiet premium neutral
+- **Hero scale (per page, decisive — do not split the difference)**: giant statement · mid editorial ·
+  mini minimalist (mini is confident restraint, not weakness)
+- **Hero architecture**: cinematic centered · asymmetric split · editorial offset · image-first with
+  restrained text · inline typographic behemoth
+- **Section system**: modular bento rhythm · alternating editorial blocks · poster-stacked storytelling ·
+  gallery-led cadence · swiss grid · asymmetric marketing flow
+- **Composition anchor (per section)**: centered statement · top-left lead / bottom-right support ·
+  bottom-left over image · off-grid editorial offset · stacked-center minimalist · image-as-canvas with
+  text in a safe area. Across a page at least 3 different anchors must appear; never repeat one anchor
+  more than twice in a row; vary the hero so the page does not open on the AI default.
+- **Background mode (per section)**: solid + inline asset · textured/paper/grid · full-bleed image with
+  tonal overlay · editorial side-image · duotone-treated image · cinematic tonal gradient (low-chroma,
+  palette-matched) · color-blocked diptych · micro-noise over solid. Be confident with backgrounds —
+  for a non-minimalist brief, at least one full-bleed/duotone/atmospheric background should appear;
+  never all-inline-asset unless the brief asks for restraint.
+- **Narrative spine (per page)**: artifact/specimen · journey/waypoints · precision instrument · living
+  system · stage/spotlight · archive/dossier. Thread it through visuals and short copy.
+
+Register still governs restraint: one signature moment, not a catalogue. The engine varies the
+composition; it never stacks five techniques into chaos.
+
+## The bar
+
+Not clean-and-correct — work a senior designer at Linear, Stripe, or Supabase would ship. Correct-but-flat
+is a failure, not a finish.