@3xhaust/oh-my-design 0.16.1

package/core/theory/layout.md

@@ -0,0 +1,159 @@
+# Layout — conditional decision material
+
+Layout is a hypothesis about reading order, task order, and relationships. No single scan
+pattern, hierarchy signal, grid unit, density, or breakpoint is universally correct. State
+the condition, predict the effect, render real content, and revise from evidence.
+
+## Start from the experience spine
+
+Before choosing a visual arrangement, write the dependency chain: what the user must notice,
+understand, compare, decide, and do. The DOM and keyboard order should follow that meaningful
+sequence even when CSS creates a different spatial composition. W3C Focus Order and technique
+C27 both make this source-order relationship an accessibility requirement, not a stylistic
+preference.
+
+Use hierarchy signals in combination. Size, weight, contrast, position, grouping, imagery,
+and motion can all attract or suppress attention; their effect depends on surrounding mass,
+content, language, viewport, and user intent. There is no authoritative universal ranking
+among them. Predict the first three attention stops, then inspect fixed-viewport squint and
+sharp renders.
+
+## Gestalt as testable grouping hypotheses
+
+- **Proximity:** closer items may be perceived as a unit. Keep an internal relationship
+  distinguishable from the gap to neighboring groups, then test at actual density.
+- **Similarity:** shared treatment may imply shared function or category. Deliberately vary
+  treatment when the semantic role differs.
+- **Closure:** space, background, edge alignment, or an incomplete contour may establish a
+  group without a border. Add containment only when the boundary is otherwise ambiguous.
+- **Common fate:** elements moving together may be interpreted as related. Choreograph only
+  relationships the content supports.
+
+These are predictions, not pixel prescriptions. A compact data table and an editorial story
+can need very different gaps while preserving the same grouping logic.
+
+## Scan behavior is conditional
+
+NN/g's F-shaped pattern describes a recurring behavior on text-heavy web content, especially
+when people scan rather than read every word. It is not a universal template and does not
+prove that every key action belongs at a particular coordinate. Use it as a warning: weak
+front-loading, uninformative headings, and long undifferentiated text make important content
+easy to miss. Strengthen information scent and meaningful headings before forcing an
+F-shaped composition.
+
+Other tasks produce other paths: comparison can move across aligned rows, search can jump to
+landmarks, and sparse storytelling can follow media or an explicit sequence. Do not claim a
+"Z-pattern law" without task-specific evidence. Record the expected path and verify it with
+content, hierarchy, focus order, and interaction evidence.
+
+## Grid and alignment
+
+A grid coordinates edges, columns, and intervals so relationships remain legible. Carbon's
+2x Grid is one documented system that combines a 2x mini unit, 8px base unit, columns,
+gutters, and margins; it is an example of a coherent system, not proof that every product
+must use those values. Apple similarly frames layout through platform context, safe areas,
+readability, and adaptation rather than a single web grid.
+
+Choose a base interval that fits the existing system, platform, type metrics, target density,
+and device-pixel behavior. Optical corrections, borders, glyph geometry, and compact control
+anatomy can legitimately fall outside it. The useful rule is traceability: repeated values
+belong to a scale; deviations name the visible problem they solve.
+
+An alignment break earns its cost when it reinforces the experience spine or concept. If
+several elements break different edges without a shared reason, the result usually weakens
+relationships. Compare an aligned and a deliberately broken candidate rather than treating
+either as inherently sophisticated.
+
+## Density and visual mass
+
+Density depends on frequency of use, expertise, task speed, content volume, screen size, and
+error cost. High density can support scanning and comparison for expert, frequent workflows;
+lower density can support comprehension, onboarding, reading, or infrequent decisions.
+"More whitespace" and "more information" are not goals by themselves.
+
+Map visual mass, not just element count. Large dark areas, saturated media, dense type,
+borders, and repeated cards can outweigh their semantic importance. Predict which regions
+dominate at desktop and mobile, render real copy/data, and correct accidental competition.
+
+## Responsive recomposition
+
+WCAG Reflow requires content to work without loss of information or functionality and
+without two-dimensional scrolling at the specified narrow equivalent, except for content
+that genuinely needs two dimensions. This is an outcome requirement, not a mandate for a
+particular breakpoint set.
+
+Add breakpoints where content, controls, relationships, or readable measures fail—not at a
+fixed list of device labels. At each transition decide explicitly whether regions:
+
+- stack while preserving dependency;
+- change order while keeping DOM/focus order meaningful;
+- collapse behind a disclosed control;
+- become horizontally scrollable because two-dimensional context is essential;
+- switch from simultaneous comparison to a staged flow.
+
+Test widths between named targets as well as the targets themselves. Fixed viewport renders
+show hierarchy and cropping; optional full-page renders show page continuity but cannot
+replace viewport evidence.
+
+## Cards and repeated modules
+
+Cards are appropriate when each item is a portable unit with a meaningful boundary. They are
+not a default composition. Repeated modules should expose the information users compare and
+distinguish true priority without manufacturing a featured item. One containment signal may
+be enough; borders, shadows, and tinted backgrounds used together can add noise, but dense or
+low-contrast contexts may need more than one signal.
+
+Ask whether section dependency would be clearer as a list, table, annotated narrative,
+split view, or continuous document before choosing cards.
+
+## Forms and task order
+
+A single vertical flow often reduces ambiguous traversal, but compact, semantically coupled
+fields can share a row when their relationship and responsive order stay clear. Labels,
+instructions, errors, and controls must remain associated programmatically and visually.
+Choose label placement from available width, translation length, scan burden, and error
+recovery—not from a universal completion-time claim.
+
+Build only reachable states. Empty, loading, error, success, disabled, and offline layouts
+must preserve the primary task, explain what changed, and provide an applicable next action.
+Do not invent states to make a checklist appear complete.
+
+## Media and memorable moments
+
+Assign media a job: establish domain, carry evidence, explain structure, demonstrate state,
+or create a concept-bearing moment. Decorative media should not claim hierarchy needed by
+the task. Distinctiveness can aid recall, but "exactly one memorable element" is not a law;
+the number and intensity depend on page length, narrative beats, and competing tasks.
+
+## Composition recipes are hypotheses
+
+The files under `core/composition/` are candidate mechanisms, not templates or defaults.
+Their breakpoint values and token slots are demonstration values. A composer may cite a
+recipe only after its condition gate matches the experience spine and must rewrite its
+structure, values, and responsive transitions for the actual content. Candidate sketches
+should compare meaningful axes rather than merely choosing different recipes.
+
+## Decision record
+
+For every consequential layout choice record:
+
+1. condition and user task;
+2. predicted attention/dependency effect;
+3. chosen mechanism and rejected alternative;
+4. desktop and mobile recomposition;
+5. fixed-viewport evidence and resulting correction.
+
+## Authoritative sources
+
+- [NN/g — F-Shaped Pattern of Reading on the Web](https://www.nngroup.com/articles/f-shaped-pattern-reading-web-content/)
+  — conditional behavior for scanning text-heavy content, not a universal page template.
+- [W3C — Understanding Reflow](https://www.w3.org/WAI/WCAG22/Understanding/reflow.html)
+  — responsive outcome and exceptions for genuinely two-dimensional content.
+- [W3C — Understanding Focus Order](https://www.w3.org/WAI/WCAG22/Understanding/focus-order.html)
+  — meaningful sequential navigation.
+- [W3C Technique C27](https://www.w3.org/WAI/WCAG22/Techniques/css/C27)
+  — matching DOM order to visual order.
+- [Carbon Design System — 2x Grid](https://carbondesignsystem.com/guidelines/2x-grid/)
+  — one documented grid system and its parts.
+- [Apple Human Interface Guidelines — Layout](https://developer.apple.com/design/human-interface-guidelines/layout)
+  — platform-aware layout and adaptation guidance.

package/core/theory/motion.md

@@ -0,0 +1,283 @@
+# Motion — decision material
+
+Motion in UI is not decoration. It is a communication channel — one that operates faster
+than reading and carries information the visual state alone cannot. Used correctly, it
+confirms what happened, shows what belongs together, and tells the eye where to look next.
+Used incorrectly, it competes with the content for attention and loses.
+
+---
+
+## Duration: what the research says
+
+Nielsen's 1993 response time research establishes three thresholds that remain empirically
+reliable across interface contexts:
+
+**Under 100ms**: perceived as instantaneous. No transition is needed or helpful — adding
+one makes a fast action feel slow, because the animation is the only delay. A hover state
+change, a button press response, a tooltip appearing: if these resolve in under 100ms,
+animating them costs more than it buys.
+
+**100–300ms**: the transition zone. Perceptible, processable, not distracting. This is
+where UI transitions belong — tab switches, modal entrances, panel slides, state changes
+the user initiated and expects to see confirmed. Material Design's motion research places
+navigation transitions at 200–300ms. Fast enough to feel responsive; long enough to read
+as an intentional event, not a glitch.
+
+**300–400ms**: the edge of interactive. Above this, the user has moved on cognitively
+before the animation resolves. Transitions over 400ms feel broken unless they are
+communicating a spatial relationship (a bottom sheet rising into position from below) or
+the concept demands it (a luxury product whose register is unhurried).
+
+**Above 400ms**: attention-consuming. Every millisecond above 400 spends attention budget
+without certain return. Micro-interactions, hover effects, and state changes must never
+exceed 400ms. Entrance animations for content on first load can reach 600ms if the page is
+itself the delivery — a portfolio case study, a campaign page — but not if the page is a
+tool the user came to use.
+
+The single most common error is 500ms ease-in-out applied uniformly. This number is wrong
+for three independent reasons: too slow for micro-interactions, too fast for meaningful
+spatial motion, and the uniform easing removes any semantic distinction between different
+kinds of change. Everything becomes the same sentence in the same tone of voice.
+
+---
+
+## Easing: the semantics of the curve
+
+The easing curve is not an aesthetic choice. It carries a specific meaning about what kind
+of event just occurred. Using ease-in where ease-out belongs is not a stylistic difference
+— it communicates the wrong thing.
+
+**ease-out** (fast start, gradual deceleration): an object arriving. The quick onset reads
+as responsive — something arrived immediately because the system responded to you. The
+gradual end reads as the object finding its place, settling. Use for: elements entering
+from outside the viewport, overlays appearing, content loading in, drawer panels opening.
+This is the "responsive" easing curve: it tells the user that the system heard them
+immediately.
+
+**ease-in** (gradual start, fast finish): an object leaving. The slow start reads as
+reluctance; the fast finish reads as completion. Use for: dismissals, removals, transitions
+out of a context. Almost never correct for entrances — a slow start reads as latency, which
+reads as a slow system, which reads as broken.
+
+**ease-in-out** (gradual start, gradual finish): an object transitioning between two
+significant states. The equal deceleration at both ends signals that the before state and
+the after state both matter — this is a state transition, not an arrival or departure.
+Use for: position changes, size changes, content crossfades where both the source and
+destination are meaningful.
+
+**linear**: no easing. Use for opacity changes on hover states only — eased opacity on a
+hover feels sluggish in a way that is hard to name but immediate to feel. Also correct for
+looping animations (a spinner, a progress bar) where acceleration and deceleration would
+produce visible stuttering on each cycle.
+
+A design system that uses a single easing curve for all motion has a vocabulary of one word.
+It can make things move, but it cannot say anything different about different movements.
+
+---
+
+## Choreography: the rules
+
+**Entrance animations fire once.** On first load, and not again. If they replay on scroll,
+the user eventually understands that scrolling triggers a performance, and they stop
+scrolling slowly enough to watch it. The animation then delays their reading without
+informing it. Scroll-triggered entrance is appropriate only when the interface is a
+*presentation* — a long-scroll narrative, a portfolio case study — not when it is a
+product the user came to use.
+
+**Sibling stagger: 40–80ms offset.** When related elements enter together, staggering their
+arrivals reads the group as a sequence — semantically correct when the elements have an
+implied order. Below 40ms the stagger is imperceptible and the stagger code is wasted.
+Above 80ms it becomes a waterfall: the user reads each element individually before the
+next arrives, turning a group reveal into a slow-loading list.
+
+**Hover feedback: under 150ms.** A hover state that takes more than 150ms to reach its
+final state reads as slow. At 80–120ms with ease-out, the system reads as immediate and
+precise. The user's pointer moved; the interface answered. Rauno Freiberg's web interface
+guidelines (interfaces.rauno.me) specify that animation duration should not exceed 200ms
+for interactions to feel immediate — 150ms for hover is the stricter constraint.
+
+**Animate only `transform` and `opacity`.** Animating `width`, `height`, `top`, `left`,
+or any property that triggers layout recalculation causes the browser to reflow and repaint
+the document on every frame. The GPU cannot help. At 60 frames per second, this causes
+visible jank on mid-range hardware. `transform: translate()` and `opacity` are composited
+off the main thread — they animate at 60fps on all reasonable hardware without touching
+layout. This is not a performance tradeoff to weigh against visual quality; it is a hard
+rule with no exceptions.
+
+**No scroll-jacking.** The user controls scroll. Intercepting scroll events to drive
+animations or reposition content removes control from the user in a way they can feel but
+not name — which is worse than a failure they can describe. NN/g ("Parallax Scrolling",
+2013) measured it: usability scores drop, and users who notice report frustration without
+being able to articulate what broke. The concept must be extraordinary to justify the cost.
+
+**`prefers-reduced-motion` is not optional.** WCAG 2.1 criterion 2.3.3 (Level AAA) requires a
+mechanism to disable non-essential animation. In practice: one media query wraps the
+entire motion layer, and in its presence, all transitions reduce to instant opacity changes
+or disappear entirely. Not because most users trigger it — because those who need it need
+it completely. A motion system that does not honour it is broken for those users,
+regardless of how thoughtfully it was built for everyone else.
+
+---
+
+## The motion budget: where to spend it
+
+Every page has an attention budget. Motion spends it. The question is not "what should
+move" — it is "what earns the most from being seen moving."
+
+The answer is almost always: one thing per context. The first-load entrance of the primary
+content. The hover state of the primary CTA. The transition between two major views. A page
+where everything moves is a screensaver: the eye has no hierarchy to follow, so it follows
+nothing in particular.
+
+Material Design's motion research (2023): assign motion to the element that carries the
+most meaning at the moment the animation fires. A form submission success animation is
+wasted if the success state is not the most important thing happening at that moment. Make
+the most important thing move; make everything else still. Still elements make moving
+elements visible; a page where everything moves makes nothing visible.
+
+---
+
+## Parallax and scroll-linked animation: the restraint case
+
+Scroll-linked parallax — backgrounds moving at a different rate than foreground content as
+the user scrolls — became a signature technique of the early 2010s and has since produced
+measurable usability damage.
+
+NN/g's research ("What Parallax Lacks", nngroup.com) documents three specific problems:
+users scroll quickly to scan for keywords of interest; parallax animations require slow
+scrolling to be processed, and users who scroll at their normal speed miss the animated
+content entirely. The animation becomes invisible to the audience it was designed for.
+Second: banner blindness — users who have seen parallax repeatedly have learned to classify
+it as decorative noise and ignore it. Third: for users with vestibular disorders, the
+dissociation between their scroll movement and the movement on screen reliably triggers
+discomfort or nausea. `prefers-reduced-motion: reduce` removes this for users who set it;
+it does not help users who have not discovered the setting.
+
+The performance case is equally clear. In 2024, real-world examples of parallax-heavy pages
+showed Largest Contentful Paint (LCP) times exceeding 8 seconds and poor INP (Interaction
+to Next Paint) scores — Core Web Vitals failures that affect search ranking as well as
+user experience.
+
+Condition → choice → reason: use scroll-linked animation only when the content is itself
+a scroll-narrative (a case study, a product demo that teaches while scrolling) and the
+concept explicitly requires it. For product UI, remove all parallax. The budget it consumes
+returns nothing.
+
+---
+
+## Microinteractions: the Saffer framework
+
+Dan Saffer's *Microinteractions: Designing with Details* (O'Reilly, 2013) defines the
+four-component structure that governs every small moment in a UI:
+
+**Trigger**: what initiates the microinteraction. Either a user action (clicking a button,
+focusing an input, swiping) or a system condition (a value threshold crossed, a timer
+expiring, a notification arriving). The trigger must be discoverable — hidden triggers are
+interaction debt, not delight.
+
+**Rules**: what happens after the trigger fires. The complete behaviour of the system in
+response — what changes, in what order, by how much. Every edge case the rules don't
+cover produces unexpected behaviour the user did not expect and the designer did not intend.
+
+**Feedback**: the signal to the user that their action was received and the rule is
+executing. Feedback can be visual (a checkbox check animates in), auditory (a success
+tone), haptic (a vibration), or motion-based (a button compresses on press). Absent
+feedback, the user cannot confirm their action was registered and will repeat it — the
+mechanism behind double-submissions on slow forms.
+
+**Loops and modes**: how long the microinteraction runs and whether it changes behaviour
+on repetition. A "like" animation that runs once is a loop of one. A notification badge
+that counts up is a loop that runs until cleared. A mode is a variant of the
+microinteraction that activates under a different state (the muted mode of a volume
+control).
+
+The design implication: every interactive element should be audited against these four
+components. If any component is missing or undefined, the interaction is incomplete. Missing
+feedback is the most common defect — it produces the user experience of interacting with
+a broken system.
+
+---
+
+## Skeleton screens vs spinners: the performance perception research
+
+Loading states are not equally effective at managing the perception of time. The choice
+between a spinner and a skeleton screen changes what the user believes about the system's
+responsiveness.
+
+**Spinners** communicate system activity: "I am working." They provide no information
+about what is coming, how much there is, or how long it will take. Under any uncertainty
+about wait duration, spinners increase anxiety — the user cannot estimate, and estimation
+is how humans manage waiting.
+
+**Skeleton screens** communicate structural presence: "The layout is here; the content is
+arriving." By showing the shape of the content before the content loads, the skeleton
+gives the brain a structure to place the incoming data. Research comparing skeleton screens
+to spinners and progress bars (NN/g, "Skeleton Screens vs. Progress Bars vs. Spinners",
+2020) shows that skeleton screens are perceived as faster even at identical actual load
+times, and studies show they can reduce abandonment by up to 30% by communicating that
+progress is already happening.
+
+Condition → choice → reason: use skeleton screens for page-level content loads where the
+layout is predictable (a list of cards, a article page, a dashboard grid). Use spinners for
+short indeterminate operations where the structural result cannot be previewed (file upload
+progress, authentication, payment processing). Never use a skeleton where the actual
+layout will be substantially different from the skeleton — a skeleton that does not match
+what loads is more disorienting than a spinner that made no promises.
+
+---
+
+## The FLIP technique: performance as a design constraint
+
+FLIP (First, Last, Invert, Play) is a browser animation technique that enables smooth
+transitions between arbitrary layout states by computing the difference between two static
+positions and animating that difference as a `transform`, rather than animating the layout
+property directly.
+
+The technique: record the element's position before the change (First). Apply the change
+and record the new position (Last). Apply a `transform` that moves the element back to its
+First position instantly (Invert). Animate the transform to zero (Play — which visually
+moves the element from its old to its new position while only touching `transform`).
+
+The design consequence: FLIP enables animations that would otherwise require animating
+layout properties — a card expanding to fill the screen, an item reordering in a list, a
+grid reconfiguring. Without FLIP, these are either unanimated (abrupt, disorienting) or
+animated with layout-touching properties (jank, dropped frames). FLIP makes them smooth
+at 60fps.
+
+The constraint: FLIP only works when the start and end states are both valid layout states.
+A design that requires animating through an intermediate state that is not a valid layout
+state cannot use FLIP. This is a genuine design constraint — some transitions need to be
+re-designed so that their start and end states are both in CSS, not procedurally computed.
+
+---
+
+## Motion cookbook
+
+The implementation primitives that put this theory into practice — split-text entrance,
+scroll-reveal, stagger orchestrator, sticky scene, section colour inversion, marquee,
+magnetic hover, page loader, number counter, image hover distortion, view transitions,
+and parallax — are in `core/motion/recipes/`. The easing token vocabulary (--ease-out-expo,
+--ease-out-back, --ease-spring, and the full curated set) is in `core/motion/easing.md`.
+Recipes reference the theory here; the hand wires the recipe parameters from the board's
+motion studies.
+
+## Sources
+
+- Nielsen, "Response Times: The 3 Important Limits" (1993) — 0.1s / 1s / 10s thresholds
+  and their perceptual basis
+- Material Design, Motion (2023) — duration guidelines, easing system, choreography rules,
+  budget allocation
+- NN/g, "Parallax Scrolling" / "What Parallax Lacks" (2013, nngroup.com) — usability
+  evidence against scroll position–driven animation; banner blindness and goal-oriented
+  scanning
+- WCAG 2.1, criterion 2.3.3 — Animation from Interactions; the accessibility baseline
+- Saffer, *Microinteractions: Designing with Details* (O'Reilly, 2013) — trigger/rules/
+  feedback/loops framework for small interaction design
+- NN/g, "Skeleton Screens vs. Progress Bars vs. Spinners" (2020) — perceived performance
+  comparison; skeleton screen abandonment reduction evidence
+- Rauno Freiberg, Web Interface Guidelines (interfaces.rauno.me) — 200ms interaction
+  ceiling, animation proportional to trigger size
+- Fast Company, "Why parallax scrolling needs to die" (2019) — performance and cognitive
+  load argument
+- Gamache, "Parallax Done Right" (Medium, 2014) — performance constraints and the GPU
+  compositing argument for transform-only animation

package/core/theory/typography.md

@@ -0,0 +1,134 @@
+# Typography: prove the text that will ship
+
+Typography starts with the reader, task, register, and actual copy. A font name or ratio is
+not a decision until the target-language specimen shows what it does to meaning, hierarchy,
+wrapping, loading, and fallback.
+
+## Evidence order
+
+Work in this order:
+
+1. Read the target-language copy deck and identify productive and expressive roles.
+2. Name the task and register: dense scanning, long reading, transactional UI, editorial
+   authority, playful showpiece, or another evidenced need.
+3. Study cited typography references for visible anatomy and behavior, not brand prestige.
+4. Build neutral specimens with the real headline, body, labels, CTA, numerals, punctuation,
+   dates, prices, identifiers, and the longest representative strings.
+5. Render at 1280x900 and 390x844 after `document.fonts.ready`.
+6. Record requested and computed browser evidence, then judge the visible result.
+
+Do not start from a generic font-name default. A familiar family can still be wrong for the
+copy, language coverage, voice, or production constraints.
+
+## Role map
+
+Separate two jobs:
+
+- **Productive type** carries navigation, body, metadata, forms, tables, states, and repeated
+  actions. It needs calm differentiation, durable glyph coverage, and predictable density.
+- **Expressive type** carries a concept-bearing display line or rare editorial moment. Its
+  face and weight must contribute meaning; size alone cannot supply the concept.
+
+One family can cover both roles. Two families can be justified when their visible anatomy
+creates a useful distinction. Start with one or two families and add another only when a
+specimen proves the existing set cannot express a required role.
+
+## Target-language and glyph coverage
+
+List the scripts and symbols that the product actually uses. For a Korean product this often
+includes Hangul syllables and jamo, Latin names and URLs, Arabic numerals, currency, dates,
+punctuation, arrows, and product-specific symbols. Test the real strings.
+
+Browser `document.fonts.check()` can show only that the browser considers a requested face
+ready for a sample; it does not prove glyph coverage. FontFace status reports declared-face
+loading state. Computed CSS can show the requested/computed family, size, weight, and line
+height. None identifies the physical font that painted every glyph.
+Visible tofu, style jumps, mismatched punctuation, or a fallback-shaped substring is a
+failure even when the API reports loaded.
+
+Hangul line breaking is a contextual author choice. W3C KLREQ describes both word-based and
+character-based practices. Test the chosen `word-break` and wrapping policy with actual copy
+at the intended container widths; do not enforce one policy for every Korean interface.
+
+## Visible anatomy and voice
+
+Compare what is visible in the specimen:
+
+- Hangul square density, counters, terminals, stroke modulation, and punctuation alignment;
+- Latin x-height, width, apertures, numeral shapes, and compatibility with Hangul color;
+- the rhythm of mixed Korean, Latin, and numeral lines;
+- whether the face sounds aligned with the recorded register rather than merely “modern.”
+
+Reject an alternative by naming the visible condition and consequence. “Too generic” is not
+enough; “the narrow Latin numerals create a second texture inside Korean prices” is evidence.
+
+## Size, measure, and line height
+
+Choose size from reading distance, role, actual copy, and container. Useful starting ranges
+are hypotheses to render, not mandates: body text often begins around the mid-teens in CSS
+pixels, compact UI may begin lower, and display roles may begin much larger. Adjust only from
+specimen evidence.
+
+Likewise, a body line height around 1.4–1.7 can be a starting test. KLREQ's 160% example is
+an example, not a universal Korean requirement. Display lines often need tighter leading,
+but the specimen must show that stacked glyphs, accents, and wrapping remain clear.
+
+Record desktop and mobile container widths, line counts, deliberate breaks, accidental
+orphans, clipping, and the relationship between primary, secondary, and CTA text. Never hide
+a heading's overflow to make a failed proof look clean.
+
+## Weight, axes, and optical size
+
+Request only weights the source provides. Compare requested and computed weights and inspect
+whether the visible face actually changes. A synthetic bold or faux italic fails when it
+distorts the intended anatomy.
+
+For variable fonts, record the file, supported axes, requested values, and relevant named
+instances. Test intermediate weights rather than assuming the browser interpolates as
+intended. Variable fonts can reduce requests in some deployments, but are not inherently
+smaller than every static subset.
+
+When the face provides an `opsz` axis, test `font-optical-sizing: auto` against an explicit
+setting. MDN documents the mechanism; the actual specimen decides whether it helps this
+face, copy, and size.
+
+## Fallback, loading, CLS, and performance
+
+Record source, licence, hosting choice, formats, unicode subsets, preload decision, and
+`font-display` behavior. Build a fallback stack that covers the same scripts. Compare its
+metrics and wraps with the primary face; use metric overrides only with measured source data.
+
+Test:
+
+- first render and post-font render for layout shift;
+- fallback and primary wraps at both proof viewports;
+- unavailable, slow, and failed font states;
+- whether critical text stays readable while loading;
+- the network cost of the files and subsets actually shipped.
+
+web.dev's font guidance is a starting reference for preload, subsetting, and layout shift.
+Performance claims belong to measured project output, never a fixed file-size promise.
+
+## Typography proof record
+
+`.omd/type-proof.md` records:
+
+- role map and target task/register;
+- family source, licence, hosting, scripts, glyphs, weights, and axes;
+- actual copy specimens;
+- requested and computed family/weight evidence;
+- desktop/mobile line, wrap, clip, orphan, and hierarchy observations;
+- fallback/loading/CLS/performance plan;
+- alternatives rejected with visible evidence;
+- a fingerprint of copy, font family/files, weights/axes, and container widths.
+
+Changing any fingerprint input invalidates the proof. After a structure is selected, repeat
+the proof inside the real production container before the visual craft checkpoint.
+
+## Sources
+
+- W3C, *Requirements for Hangul Text Layout and Typography (KLREQ)*.
+- web.dev, *Font best practices*.
+- MDN, *CSS Font Loading API* and *font-optical-sizing*.
+- U.S. Web Design System, typography guidance.
+- Carbon Design System, productive and expressive type roles.