freecodego 0.1.7-alpha.2.2 → 0.1.7-rc.2.3

package/dist/assets/design/craft/laws-of-ux.md

@@ -0,0 +1,296 @@
+# Laws of UX craft rules
+
+Universal cognitive, perceptual, and behavioral heuristics that decide
+what a UI composes — how many pricing tiers fit on a screen, where a
+primary action anchors in scanning order, when a progress indicator
+earns its place, why a settings list needs grouping. The active
+`DESIGN.md` decides brand visual language; the existing craft files
+decide rendering rules (color, typography, motion, states, ARIA, RTL,
+forms); this file decides composition rules grounded in named research.
+
+> Distilled from primary sources: Hick (1952) + Hyman (1953), Miller
+> (1956) for chunking / `7±2` channel capacity, Cowan (2001) for the
+> modern ~4 working-memory bound, Fitts (1954), Wertheimer (1923) for
+> proximity / similarity / Prägnanz, Palmer (1992) for Common Region,
+> Palmer & Rock (1994) for Uniform Connectedness, Kahneman /
+> Fredrickson / Schreiber / Redelmeier (1993) for Peak-End, Zeigarnik
+> (1927), Csíkszentmihályi (1975), Hull (1932), von Restorff (1933),
+> Broadbent (1958), Sweller (1988), Postel (RFC 760, 1980), Carroll &
+> Rosson (1987), Tversky & Kahneman (1974) for Anchoring, Kurosu &
+> Kashimura (1995), Iyengar & Lepper (2000), Toffler (1970), Pareto
+> (c.1906) / Juran (*Quality Control Handbook*, 1951), Ebbinghaus
+> (1885), Ockham (14th c.), Tesler at Apple (1980s), Nielsen (2000),
+> Norman *POET* (1988), Parkinson (1955).
+
+## Prior art and scope
+
+Existing public catalogs of UX heuristics (Yablonski's lawsofux.com,
+NN/g's 10 usability heuristics, Material 3 motion + interaction
+guidance, Apple HIG, Baymard Institute checkout research) inventory the
+laws but rarely tie each one to a concrete code-gen directive. This
+file does the translation: every entry ends with one actionable move
+for an HTML / Tailwind / React-emitting agent. Sibling craft files
+(`accessibility-baseline.md`, `state-coverage.md`, `typography.md`,
+`anti-ai-slop.md`, `color.md`, `animation-discipline.md`,
+`form-validation.md`) own the auto-checked rules; this file names the
+underlying law and surfaces the folklore. Out of scope: Weber-Fechner
+psychophysics and Signal Detection Theory — both apply to UI but the
+prompt-emission directives are too narrow to earn a slot here. Add
+later if a skill needs them.
+
+The rules below are guidance, not auto-checked. Reviewers and the agent
+apply them; the linter does not. Where a law has a sibling rule already
+auto-checked elsewhere — touch-target floor in
+`accessibility-baseline.md`, the 300 ms / 2 s / 10 s / 30 s / 60 s
+loading thresholds in `state-coverage.md`, ALL CAPS letter-spacing in
+`typography.md`, the indigo / gradient / emoji-icon list in
+`anti-ai-slop.md` — the entry below cross-references rather than
+duplicates.
+
+## Perception and visual grouping
+
+Five Gestalt laws plus three attention-and-recognition laws govern how
+the eye groups elements before the brain reads them.
+
+- **Law of Proximity** (Wertheimer, 1923). Objects near each other read
+  as a group. Cheapest grouping signal — cheaper than borders or shared
+  color. Apply variable vertical rhythm: 8–12 px within a group,
+  32–48 px between groups. Uniform spacing reads as nothing being
+  grouped.
+- **Law of Similarity** (Wertheimer, 1923). Visually similar elements
+  read as a group. Equivalent affordances must share treatment — every
+  list row identical class set, every secondary button identical, every
+  destructive action identical. Visible deviation is reserved for the
+  one item meant to draw attention (the recommended pricing tier, the
+  selected nav item).
+- **Law of Common Region** (Palmer, 1992). A shared bounded area binds
+  enclosed elements. Use enclosure when proximity is not enough — and
+  reserve it. Concrete numbers: padding ≥16 px inside the region,
+  distinct surface (border + tinted background, or card chrome at
+  ≥1 px hairline). A page where every section is bordered destroys the
+  signal.
+- **Law of Prägnanz / Good Figure** (Wertheimer, 1923). The eye
+  resolves complex layouts into the simplest underlying form. Designs
+  that align with a clear underlying grid (12-column, F-pattern,
+  4-quadrant) feel inevitable; ornate breaks that add nothing semantic
+  feel arbitrary.
+- **Law of Uniform Connectedness** (Palmer & Rock, 1994). The
+  strongest grouping signal in the Gestalt hierarchy: connected lines,
+  shared toolbars, or bracketing containers tie items together more
+  strongly than proximity or similarity. Use for wizard steps,
+  comparison sets, and explicit navigation flows.
+- **Selective Attention** (Broadbent, *Perception and Communication*,
+  1958). Cognitive bandwidth is finite. Users filter aggressively and
+  ignore anything that looks irrelevant to their goal — banner blindness
+  comes from this. Reserve the strongest visual contrast for the single
+  goal-relevant action; let supporting content recede in weight.
+- **Von Restorff Effect** (von Restorff, 1933). The item that differs
+  from a uniform field is the one most likely to be remembered. Make
+  the recommended pricing tier, the active nav item, the warning state
+  visually distinct. Pair contrast with a non-color signal (icon, text
+  label, position) — `accessibility-baseline.md` rules out color-alone
+  signaling.
+- **Aesthetic-Usability Effect** (Kurosu & Kashimura, Hitachi Design
+  Center, 1995). Visual polish biases perceived usability. Refined
+  typography, generous whitespace, and a calm palette earn the benefit
+  of the doubt for minor friction. Never substitutes for measurable
+  usability or for `state-coverage.md`'s required-states rule.
+
+## Decision-making
+
+Six laws govern how fast and how well users decide when an interface
+offers a choice.
+
+- **Hick's Law** (Hick, 1952; Hyman, 1953 replication). Decision time
+  grows roughly log(n+1) with the number of equivalent options. Cap any
+  single decision-screen to 3–5 visible primary options; collapse the
+  rest behind a "More" / progressive disclosure pattern; visually
+  distinguish the recommended choice. Aggressive truncation that hides
+  the path forward is the opposite failure mode — surface the full
+  option set, just don't render every option at the same visual weight.
+- **Choice Overload** (Iyengar & Lepper, *Journal of Personality and
+  Social Psychology*, 2000; framing dates to Toffler, *Future Shock*,
+  1970). Too many roughly-equivalent options stall or abandon the
+  decision. Pricing pages: 3–4 tiers, exactly one marked recommended.
+  Product grids: 6–9 hero cards above the fold. Settings panels: ≤5
+  named groups. Never emit a flat wall of equivalents.
+- **Anchoring** (Tversky & Kahneman, *Science* 185:1124–1131, 1974).
+  The first number a user sees re-weights every subsequent number.
+  Place the recommended pricing tier where it anchors the comparison;
+  render yearly-billing savings as concrete dollar deltas, not just
+  percentage badges; pre-select the safer default in radio groups.
+  Visual weight matches intended decision weight.
+- **Pareto Principle / 80-20** (Pareto, c.1906; Juran, *Quality Control
+  Handbook*, 1951 — popularized the management-application framing). A
+  small share of features drives most of the value. Identify the 2–3 actions
+  that drive the dominant journey for the target persona; emphasize
+  those visually; demote the long tail to overflow menus, footer
+  surfaces, or settings.
+- **Tesler's Law / Conservation of Complexity** (Tesler, Apple, 1980s).
+  Every product has an irreducible amount of complexity. The design
+  choice is *where* it lives — engineering team, interface, user — not
+  whether to eliminate it. When complexity reaches the user, surface
+  contextual guidance (tooltips, smart defaults, inline empty-state
+  coaching, progressive disclosure) at the exact step where it
+  surfaces. Hiding it is not the same as removing it.
+- **Occam's Razor** (Ockham, 14th c.). Among options that explain the
+  data equally well, prefer the one with the fewest assumptions. Specify
+  a minimal element inventory; forbid decorative chrome that doesn't
+  serve a stated user task. The law constrains assumptions, not feature
+  count — a "minimum viable" framing misreads it.
+
+## Memory and learning
+
+Five laws cover how working memory handles information density and
+what the user retains afterward.
+
+- **Miller's Law and Chunking** (Miller, *The Magical Number Seven,
+  Plus or Minus Two*, *Psychological Review*, 1956 — channel capacity /
+  `7±2` and chunking; Cowan, *Behavioral and Brain Sciences* 24:1, 2001
+  for the modern ~4-item working-memory bound). Working memory holds
+  about four items reliably and up to seven for short-term recall. Each
+  slot can hold a *larger familiar unit*, constrained by the user's
+  domain knowledge — chunking does not let you pack arbitrary content
+  into a single slot. Often misread as a rule about menu length;
+  Miller's paper is about chunks. Group related fields with clear
+  section headings, dividers, or card containers. A settings page with
+  sections "Account / Notifications / Privacy / Billing / Danger zone"
+  beats one flat list of 30 toggles.
+- **Working Memory** (Baddeley & Hitch, 1974; lineage to Atkinson &
+  Shiffrin, 1968). Items decay in seconds without rehearsal. Recognition
+  beats recall: persisting prior context across screens, marking visited
+  elements, and surfacing comparison views beats forcing the user to
+  memorize. On dashboards specifically: sticky filter chips, last-N
+  selections persisted, breadcrumbs that include applied filters.
+- **Serial Position Effect** (Ebbinghaus, *Über das Gedächtnis*, 1885).
+  Recall favors the extremes — primacy at the start, recency at the
+  end — while middle items fade. Anchor the most important nav items at
+  the leftmost and rightmost positions of a horizontal menu; cluster
+  utilities in the middle.
+- **Peak-End Rule** (Kahneman, Fredrickson, Schreiber, Redelmeier,
+  *Psychological Science*, 1993). Memory of an experience is dominated
+  by the emotional peak and the ending, not the average. Stage a
+  high-effort celebratory success state; let intermediate steps stay
+  calm. Mediocre middles matter less than a strong close. The peak
+  belongs at the *end* of a flow, not as arbitrary mid-flow motion —
+  `animation-discipline.md` rejects motion that performs (rather than
+  confirms) a state change.
+- **Zeigarnik Effect** (Zeigarnik, *Über das Behalten erledigter und
+  unerledigter Handlungen*, 1927). Uncompleted tasks create cognitive
+  tension that pulls the user back. Visible progress ("3 of 5 steps",
+  greyed-out next sections) converts that tension into completion
+  pressure. Reserve for genuinely beneficial flows like onboarding;
+  applying the same lever to streaks, daily-quest counters, or notification-
+  reduction nags is a dark pattern.
+
+## Interaction and motor
+
+Five laws cover how fast and how accurately users can act on the UI.
+
+- **Fitts's Law** (Fitts, *Journal of Experimental Psychology*, 1954).
+  Time to acquire a target depends on its distance and size — bigger
+  and closer is faster. Spacing between adjacent hit zones matters as
+  much as size. Pair with `accessibility-baseline.md`'s 24 × 24 CSS px
+  AA touch-target floor; on mobile, place high-frequency controls in
+  the natural thumb arc.
+- **Doherty Threshold** (Doherty & Thadani, *IBM Systems Journal*,
+  1982). Sub-second feedback keeps users in flow; latency above ~1 s
+  breaks attention. The implementable directive lives in
+  `state-coverage.md`'s loading-threshold table (no indicator under
+  300 ms; skeleton 300 ms – 2 s; labelled spinner 2 – 10 s; determinate
+  bar with cancel 10 – 60 s; stop and offer error/retry past 60 s).
+  This entry exists to name the underlying law and flag its folklore
+  (the 400 ms number doesn't appear in the 1982 paper — see
+  `animation-discipline.md` for the 400 ms folklore trace).
+- **Flow** (Csíkszentmihályi, *Beyond Boredom and Anxiety*, 1975). Flow
+  sits in the balance between challenge and skill — too hard breeds
+  frustration, too easy breeds boredom. Continuous feedback and a clear
+  sense of control keep the user inside the state. System friction and
+  latency are the fastest ways to break it.
+- **Goal-Gradient Effect** (Hull, *Psychological Review*, 1932; Kivetz,
+  Urminsky, Zheng, 2006 for the punch-card replication). Motivation to
+  finish rises as the goal gets closer. Multi-step flows render with a
+  prominent progress indicator that reflects *real* endowed progress —
+  show completed prerequisites when they truly exist (saved profile,
+  imported team, prior survey answer). When no real prerequisite
+  exists, render the current step honestly as `1 of N` with the
+  empty/current-step state clearly marked. Hull's hypothesis is
+  descriptive; treating it as license for fabricated progress, streak
+  dark patterns, or loyalty-program quota inflation is a misread.
+- **Postel's Law / Robustness Principle** (Postel, RFC 760, 1980). "Be
+  liberal in what you accept, conservative in what you send." Take
+  input in whatever shape users naturally give it (phone numbers with
+  or without dashes, dates in mixed formats, percentages with or
+  without `%`); normalize internally to a canonical form; emit one
+  consistent format on output. The error-timing and ARIA-wiring half
+  lives in `form-validation.md`; the input-tolerance half is the
+  directive above. RFC 9413 (Thomson, IAB, 2023; built on the earlier
+  `draft-iab-protocol-maintenance`) retracts the maxim for protocol
+  design citing security surface; the UX-input application stands.
+
+## Behavior and expectation
+
+Five laws cover what users predict and how that prediction interacts
+with the rendered surface.
+
+- **Jakob's Law** (Nielsen, Nielsen Norman Group, 2000). Users spend
+  most of their time on other sites and expect yours to work the same.
+  Reuse category convention — nav placement, cart icon, settings gear,
+  primary CTA in the upper right of a SaaS landing — so the user spends
+  zero cycles relearning interaction grammar. Novelty must earn its
+  keep against the convention's ROI; "innovate everywhere" is the
+  opposite failure mode.
+- **Mental Model** (Craik, *The Nature of Explanation*, 1943; Norman,
+  *POET / The Psychology of Everyday Things*, 1988). Every user
+  arrives with a prior built from competitor products and the physical
+  world. When the prediction holds, the product feels intuitive; when
+  it breaks, friction shows up as confusion, not curiosity. When the
+  brief names a reference product, anchor explicitly — capture the
+  reference in the prompt and the agent inherits a transferable
+  interaction grammar.
+- **Paradox of the Active User** (Carroll & Rosson, in *Interfacing
+  Thought: Cognitive Aspects of Human-Computer Interaction*, MIT Press,
+  1987, pp. 80–111). Users skip the manual and start using the
+  software immediately, even when reading it would speed them up. Bake
+  guidance into the surface itself — empty-state coaching, inline
+  tooltips, contextual hints — at the action point.
+- **Parkinson's Law** (Parkinson, *The Economist*, 1955). Work expands
+  to fill the time allotted to it. Loose interfaces let users dawdle;
+  cut friction and pre-fill what you can — autofill, smart defaults,
+  saved state — so a checkout finishes faster than the user expected.
+  Beating anticipated duration becomes the felt win.
+- **Cognitive Load** (Sweller, *Cognitive Science*, 1988). Total
+  mental effort splits into intrinsic (the task's inherent difficulty)
+  and extraneous (poor layout, jargon, inconsistent patterns, visual
+  noise). Designers can't reduce intrinsic load; they own extraneous
+  fully. The visual-restraint directives (single accent in `color.md`,
+  three-weight typography rhythm in `typography.md`, P0 anti-default
+  list in `anti-ai-slop.md`) already constrain extraneous load; this
+  entry exists to name the cognitive cost the sibling rules reduce.
+
+## Common mistakes (lint these)
+
+Folklore corrections that don't survive a primary-source check, in the
+same vein as the busts already documented in `animation-discipline.md`
+and `accessibility-baseline.md`. The first three are attribution
+corrections (year / venue / institution) the body entries already
+applied — restated here so a reviewer reading just this section sees
+them. The remainder are folklore not addressed in the body.
+
+- "Anchoring effect = Tversky & Kahneman 1972." Wrong year. The
+  *Science* paper introducing the anchoring framing is 1974; the 1972
+  paper is "Subjective probability: A judgment of representativeness"
+  (different work).
+- "Tesler's Law was developed at Xerox PARC." Tesler left PARC for
+  Apple in 1980; the Conservation-of-Complexity formulation traces to
+  his Apple years.
+- "Paradox of the Active User was a CACM article." It's a chapter in
+  Carroll's *Interfacing Thought* (MIT Press, 1987), not CACM.
+- "Selective Attention = solved by red dots and badges." Repeated
+  attention-grabbers train banner blindness. Reserve the strongest
+  contrast for one goal-relevant action per surface.
+- "Fitts's Law alone is enough for touch targets." Fitts gives the
+  speed-accuracy tradeoff. WCAG 2.2 SC 2.5.8 sets the AA floor at
+  24 × 24 CSS px (`accessibility-baseline.md`); iOS HIG suggests
+  44 × 44 pt; Material 3 suggests 48 × 48 dp. Fitts plus the
+  platform floor — never just Fitts.

package/dist/assets/design/craft/rtl-and-bidi.md

@@ -0,0 +1,186 @@
+# RTL and bidirectional craft rules
+
+Universal rules for right-to-left layout and bidirectional text. The
+active `DESIGN.md` decides brand visual language; this file decides
+how that language behaves when the script reads from the right or
+mixes direction within a line.
+
+> Grounded in primary sources: Unicode UAX #9 revision 51 (Sept 2025)
+> + Unicode 17.0, CSS Logical Properties Level 1, HTML Living Standard
+> (`dir`, `<bdi>`), Tailwind v4.0/v4.2 changelogs, W3C alreq,
+> Material 3 RTL guidance, Apple HIG internationalization.
+
+## Base direction and language
+
+Every full-page RTL artifact needs `<html dir="rtl" lang="ar">` (or
+the matching `lang` for Hebrew, Persian, Urdu). The `lang` attribute
+drives font-stack selection, hyphenation, locale-aware speech
+synthesis, and search-engine indexing — `dir` alone isn't enough.
+Three patterns cover the common cases:
+
+- **Full-page RTL.** `<html dir="rtl" lang="ar">`. Everything inside inherits.
+- **Mixed-language subtree.** Nest `<section dir="ltr" lang="en">…</section>` (or vice versa) when an embedded block uses a different script. Code samples, English citations, foreign brand names.
+- **User-generated content of unknown direction.** `dir="auto"` on the paragraph. The browser resolves direction from the first strong directional character in the run.
+
+Setting `lang` without `dir` is fine **at the document root in a
+default-LTR page** — English doesn't need `dir="ltr"` there because
+the bidi base direction is already LTR. Inside any opposite-direction
+ancestor, `lang` does not reset the inherited base direction, so set
+both `lang` and `dir` on the subtree (`<section dir="ltr" lang="en">`).
+Setting `dir` without `lang` is rarely correct — at minimum drop the
+appropriate ISO-639 tag in.
+
+## Logical properties first
+
+Hardcoded `left` / `right` is a bug for any layout that might render
+RTL. Use logical properties on the inline axis. Use them on the block
+axis when the writing-mode varies; physical otherwise.
+
+| Logical | LTR resolves to | RTL resolves to |
+|---|---|---|
+| `margin-inline-start` / `padding-inline-start` / `inset-inline-start` | left | right |
+| `margin-inline-end` / `padding-inline-end` / `inset-inline-end` | right | left |
+| `border-inline-start` | border-left | border-right |
+| `border-start-start-radius` | border-top-left-radius | border-top-right-radius |
+| `text-align: start` / `text-align: end` | left / right | right / left |
+| `inline-size` / `block-size` | width / height | width / height |
+
+Browser support: core inline-axis logical properties are Baseline
+Widely Available (Chrome 87, Safari 14.1, Firefox 66; ≥95% global as
+of 2026-05).
+
+**Tailwind v4 changes the answer for new projects.** v4.0 (2025-01-22)
+folded inline-axis logical utilities into core (`ms-*`, `me-*`, `ps-*`,
+`pe-*`, `start-*`, `end-*`). v4.2 (2026-02-18) added the block-axis
+set (`mbs-*`, `mbe-*`, `pbs-*`, `pbe-*`) and renamed the inset
+utilities: `start-*` / `end-*` are deprecated (still work) in favor
+of `inset-s-*` / `inset-e-*`. The `tailwindcss-rtl` plugin is obsolete.
+Don't write `[dir="rtl"]:` overrides for spacing on Tailwind v4.
+
+## Bidirectional text
+
+UAX #9 rev 51 (Sept 2025) is a version stamp for Unicode 17.0. No
+algorithm change; `max_depth = 125` is permanently locked forward.
+
+UAX #9 defines two distinct families of bidi formatting characters
+that solve different problems:
+
+- **Isolate controls** (modern, prefer these): U+2066 LRI, U+2067 RLI, U+2068 FSI — opened with these, all closed with U+2069 PDI. An isolated run does not affect, and is not affected by, the surrounding paragraph's bidi resolution. Use FSI when the embedded run's direction is unknown ahead of time.
+- **Embedding / override controls** (legacy): U+202A LRE, U+202B RLE, U+202D LRO, U+202E RLO — all closed with U+202C PDF. These nest within the surrounding paragraph rather than isolating from it; LRO/RLO additionally force a direction onto neutral characters. Newer code should use isolates; touch embeddings only when interoperating with text from systems that emit them.
+
+**Use `<bdi>` in HTML; in plain text, pick the isolate that matches
+what you know about the run.** UAX #9 §2.7: *"where available, markup
+should be used instead of the explicit formatting characters."*
+`<bdi>` has been Baseline Widely Available since January 2020.
+Reach for control characters only in plain-text contexts (logs,
+plain-text emails, terminal output). When you do:
+
+- **LRI U+2066 + PDI U+2069** for known-LTR runs (English name in an Arabic paragraph, code-style identifiers, phone numbers).
+- **RLI U+2067 + PDI U+2069** for known-RTL runs (Arabic name in an English paragraph).
+- **FSI U+2068 + PDI U+2069** for unknown direction (UGC where the author and language can vary).
+
+Don't reach for FSI as the default — it auto-detects from the first
+strong character, which is the wrong choice when you already know
+what direction the run should be.
+
+`dir="auto"` on a paragraph or `<bdi>` lets the browser detect
+direction from the first strong directional character. Best for
+user-generated content where direction isn't known at author time.
+
+## What mirrors and what doesn't
+
+Mirroring isn't universal. The rules below are unanimous across
+Material 3 RTL guidance and Apple HIG internationalization.
+
+**Must mirror:**
+
+- Directional arrows (back / forward / next / previous), navigation rail position, tab order, calendar-grid weekday order.
+- Slider fill direction and **non-media** progress-bar fill (a download progress bar, a form-completion bar, an upload status). Media scrubbers stay LTR — see the Media row below.
+- Checkbox-and-label position. Label sits to the right in LTR, to the left in RTL.
+- Phone-number and IBAN affordances when the surrounding paragraph is RTL but the value itself is LTR — wrap the value in `<bdi dir="ltr">` (or `<span dir="ltr">`) so the digits don't reflow. Bare `<bdi>` is not enough: phone numbers and account numbers contain mostly weak / neutral characters, so first-strong direction detection is unreliable. Force LTR explicitly.
+
+**Must not mirror:**
+
+- Clock faces. Clockwise is universal.
+- Circular refresh / sync / reload icons. Same reason.
+- Media playback controls (play / pause / fast-forward / rewind) **and the media scrubber / progress timeline**. They represent tape direction, not reading direction.
+- Charts and graphs. X-axis stays mathematical, not linguistic.
+- Photographs, brand logos, physical-object icons (camera, keyboard, headphones). Identity over direction.
+
+**Numerals are not a mirroring decision.** They follow locale, not
+paragraph direction. Arabic-Indic digits carry bidi class **AN**, not
+EN — affects how they sit inside mixed-direction lines but does not
+flip them.
+
+**Single live conflict between platforms:** the search icon. SF Symbols
+ships an RTL `magnifyingglass` variant (Apple flips it). Material 3
+says don't flip the magnifying glass (handle stays bottom-right).
+Decide per-platform; don't synthesize a single rule.
+
+## Typography rules anchored here
+
+Two RTL-coupled typography rules sit in this file because they cause
+breakage at the layout level. The full Arabic / Hebrew typography
+guide (font picks, harakat line-height, OpenType shaping, mixed-script
+fallback chains) belongs in a future `craft/arabic-hebrew-typography.md`.
+
+- **Never apply CSS `letter-spacing` to Arabic runs.** alreq treats
+  letter-spacing as a boundary concept, not a uniform tracking value.
+  Applying tracking breaks the cursive joining the script depends on.
+- **Body type for Arabic runs ~14-18 px with line-height 1.5-1.75** to
+  give harakat (diacritics) clearance. Latin defaults are too tight.
+
+## Native mobile RTL parity
+
+Web RTL handling does not auto-translate to mobile. Each platform has
+its own direction primitive. Skills that emit web-only artifacts can
+skim this section; it's the entry point for skills that ship to
+mobile (mobile-onboarding, mobile-app, etc.).
+
+| Platform | Direction primitive | Spacing |
+|---|---|---|
+| iOS UIKit | `semanticContentAttribute = .forceRightToLeft` | `NSDirectionalEdgeInsets` |
+| iOS SwiftUI | `.environment(\.layoutDirection, .rightToLeft)` | `EdgeInsets` with `leading` / `trailing` |
+| Android Compose | `CompositionLocalProvider(LocalLayoutDirection provides LayoutDirection.Rtl)` | `PaddingValues` accepts start / end |
+| Flutter | `Directionality(textDirection: TextDirection.rtl)` | `EdgeInsetsDirectional.fromSTEB(...)` |
+| React Native | `I18nManager.forceRTL(true)` (requires native reload; no `forceLTR` parity, no `react-native-web` support) | `marginStart` / `marginEnd` |
+
+The rule across all platforms: prefer the directional primitive over
+the absolute one. `EdgeInsets.left/right` in Flutter, `paddingLeft` /
+`paddingRight` in Android, leading-vs-trailing in iOS — these are bugs
+waiting for an Arabic deployment.
+
+## Forms in RTL
+
+Form fields commonly mix scripts. Three rules cover most of it.
+
+- **`<input dir="auto">`** for any field whose value's direction is uncertain (search boxes, comment fields, free-text inputs). The browser detects from the first strong directional character.
+- **Force LTR on intrinsically-LTR fields** even inside an RTL paragraph: email, URL, phone, IBAN, credit-card. `<input type="email" dir="ltr">`.
+- **Wrap rendered values in `<bdi>`** when displaying mixed-script content (a username inside a paragraph, a model number inside a description). Stops the surrounding direction from rearranging the embedded value. For values whose direction is fixed and weak-character-heavy (phone, IBAN, card number), use `<bdi dir="ltr">` rather than bare `<bdi>` so first-strong detection doesn't misclassify.
+
+## Common mistakes (lint these)
+
+Mechanically lintable items can be flagged from CSS / source alone.
+Script-aware items need to detect Arabic / Hebrew runs in the
+rendered text and have legitimate exceptions (chart axes, physical
+icons, platform-specific placement).
+
+**Mechanically lintable:**
+
+- Hardcoded `left` / `right` / `text-align: left` in new CSS — bug for any layout that may render RTL. Exceptions: chart x-axes, physical-object icons, platform-pinned UI like a status-bar clock. Lint with an allow-list rather than blanket banning.
+- "Tailwind v4.2 logical-utility rename is `inline-s-*` / `inline-e-*`" — wrong family. Those are size utilities. The inset rename is `inset-s-*` / `inset-e-*`.
+- "WebKit doesn't support U+2066-U+2069" — wrong, they're interoperable across modern browsers. The "still missing" claim traces to a stale 2015 W3C test snapshot.
+- Setting `dir="rtl"` without `lang="ar"` (or matching). Lint together; `dir` alone misses the font-stack and locale path.
+- Flutter `EdgeInsets.left/right` in code that needs to render RTL. Use `EdgeInsetsDirectional.start/end`.
+
+**Needs script detection (will false-positive without it):**
+
+- "Use `text-justify: kashida` for Arabic" — no browser implements it. CSS `text-align: justify` adds inter-word spacing and looks unnatural in Arabic; kashida elongation is the correct form, but it isn't shippable on the web today.
+- Italics on Arabic or Hebrew text. Neither script has an italic tradition.
+- CSS `letter-spacing` applied to Arabic. Breaks cursive joining (alreq treats it as a boundary concept, not a uniform tracking value).
+- Lorem Ipsum used for RTL prototyping. Arabic word lengths, connection behaviors, and vertical extents differ; use real Arabic / Hebrew text.
+
+**HTML semantics:**
+
+- Reaching for CSS bidi controls (`unicode-bidi: isolate` / `plaintext` / `embed`) for inline runs when `<bdi>` or a `dir`-bearing element does the job. Prefer semantic isolation in HTML for inline content; `unicode-bidi: plaintext` operates on a different surface (it changes how base direction is determined for each plaintext paragraph in a block) and should only be used when that block-level paragraph behavior is explicitly required and tested. The two are not drop-in equivalents — don't lint one as a replacement for the other.
+- Bare `<bdi>` around phone / IBAN / card numbers in an RTL paragraph. First-strong detection on weak/neutral characters is unreliable; force `dir="ltr"` explicitly.

package/dist/assets/design/craft/state-coverage.md

@@ -0,0 +1,134 @@
+# State coverage craft rules
+
+Universal rules for what every interactive surface must render. The active
+`DESIGN.md` decides how each state looks; this file decides which states must
+exist and what they must contain. The single most reliable AI-design failure
+is shipping only the populated state.
+
+> Distilled from WCAG 2.2, NN/g, Material Design 3, Apple HIG, and Baymard
+> Institute checkout research.
+
+## The five required states
+
+Every surface that fetches, transforms, or accepts data must render all five.
+
+| State | Triggered when | Must contain |
+|---|---|---|
+| **Loading** | Data is in flight | Skeleton, spinner, or shell — plus a 15 s "taking longer than expected" fallback |
+| **Empty** | No records yet, or query returned nothing | Headline, plain explanation, primary CTA |
+| **Error** | Fetch failed, server failure, validation rejection | Plain-language cause, recovery action, preserved user input |
+| **Populated** | Data present, primary case | The state the design was actually drawn for |
+| **Edge** | Extreme volume, long strings, missing optional fields, RTL or long-word content, partial network | Layout that does not break |
+
+Render-and-screenshot test: every list, table, card, form, and panel in the
+artifact has all five. Missing states are the most common silent failure of
+AI-generated UI.
+
+**Test matrix.** Concrete edge scenarios the surface must survive:
+
+| Skill type | Edge scenario |
+|---|---|
+| Dashboard / table | 10,000+ rows, all numeric columns, sort + filter applied |
+| Mobile card / list | 200-char title, missing avatar, missing secondary CTA |
+| Form | All optional fields empty, all required fields at max length |
+| Search results | Single-character query, query with only special chars, 1,000+ result count |
+| Detail view | Missing all optional metadata, RTL primary content with LTR embeds |
+
+## Form-specific states
+
+Forms add three states on top of the five.
+
+| State | Triggered when | Behavior |
+|---|---|---|
+| **Untouched** | Field has not yet had focus | Default styling; no validation messages |
+| **Dirty (valid)** | User typed and field passes validation | Persistent helper text remains; no success-coloring |
+| **Submitted-pending** | Submit clicked, awaiting server | Submit button enters loading state; fields lock against re-submission |
+
+Validation timing: validate **on blur**, not on first keystroke. For password
+and similar live fields, validate on each keystroke *only after the first
+blur*. Remove the error message the instant input becomes valid.
+
+## Empty state composition
+
+Empty is not the absence of state. It is its own state with a job.
+
+- **First-use empty** — illustration + headline + value sentence + primary CTA. The empty is the onboarding moment.
+- **No-results empty** — echo the query, suggest alternatives, never leave a true blank.
+- **Cleared empty** — celebratory phrasing, optional next-action.
+- **Error-as-empty** — never. An error is its own state with recovery information; do not collapse error into empty.
+
+**Server-driven vs client-driven.** When a search or query API can return fallback content in the empty payload (suggestions, related categories, popular results), prefer that over a client-side echo. Algolia, Elastic, and most modern search backends support this — the server has more context for what "no results, but maybe try X" should mean.
+
+## Error state composition
+
+Every error must answer three questions, in this order:
+
+1. **What happened.** "Your card was declined." Not "Something went wrong."
+2. **Why, if knowable.** "Insufficient funds." Or "Network unreachable — check your connection."
+3. **What the user can do.** A retry button, an alternative path, or a support link.
+
+Preserve user input across the error. The form must not clear on submit
+failure.
+
+Severity tiers:
+
+- **Field-level** — red border, inline message, focus moves to the field.
+- **Form-level** — error summary banner at top + per-field markers.
+- **Section-level** — inline panel with retry, surrounding sections still functional.
+- **Page-level** — full error state with illustration and recovery CTA.
+- **App-level** — persistent banner or modal for critical loss-of-functionality.
+
+Match severity to surface scope. A field validation failure does not warrant
+a page-level error.
+
+**Retry discipline.** A retry surface is not a button alone. It has timing rules:
+
+- First retry fires immediately on user click.
+- Second and third retries use exponential backoff: 2 s, 4 s, 8 s max.
+- After 3 failed retries, replace "Retry" with "Contact support" plus a copyable error ID. The user has done their job; the system now needs a human.
+- Show "Last attempted: Xs ago" on the error surface after the first retry, so the user knows how stale the failure is.
+
+## Loading state thresholds
+
+Pick the indicator by expected duration, not by what's available in the
+component library.
+
+| Duration | Indicator |
+|---|---|
+| 0–300 ms | None. Render synchronously; users perceive no delay. |
+| 300 ms – 2 s | Subtle spinner or skeleton. |
+| 2 – 10 s | Skeleton matched to expected layout, or labelled spinner ("Loading payments…"). |
+| 10 – 30 s | Determinate progress bar with cancel option. |
+| 30 – 60 s | Progress bar with explicit cancel affordance. The "taking longer than expected" notice already appeared at 15 s; do not repeat it. |
+| 60 s+ | Stop animation. Show error with retry, cancel, or continue. |
+
+Never leave a spinner running indefinitely. Start a timeout on every request.
+
+## ARIA and focus rules
+
+State changes must be announced and focused correctly.
+
+| Change | ARIA | Focus action |
+|---|---|---|
+| Inline error on submit | `role="alert"` on the message | Move focus to first error field |
+| Toast / non-urgent confirmation | `role="status"` (polite live region) | Do not move focus |
+| Critical error or destructive confirmation | `role="alertdialog"` (assertive) | Move focus to dialog |
+| Loading begins | `role="status"` announcement ("Loading…") | Do not move focus to spinner |
+| Loading ends, content appears | — | Move focus to loaded content if action was user-initiated |
+
+Live region containers must exist in the DOM before content is injected.
+Adding `aria-live` simultaneously with content does not trigger an
+announcement.
+
+## Common mistakes (lint these)
+
+- Surface renders only the populated state; loading, empty, error, and edge are absent.
+- Empty state is a literal blank or "No data" text with no headline, explanation, or action.
+- Error message reads "Something went wrong" with no cause or recovery.
+- Spinner with no timeout; runs indefinitely on slow or failed requests.
+- Submit clears form fields on validation failure, forcing re-entry.
+- Inline validation fires on first keystroke instead of on blur.
+- Full-page loading replaces the chrome when only one section is fetching.
+- Toast appears at a different screen position than previous toasts in the same artifact.
+- Color alone conveys error state — no icon, no text label.
+- Auto-dismissing toast cannot be paused on hover or focus (WCAG SC 2.2.1).