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

package/dist/assets/design/craft/typography-hierarchy-editorial.md

@@ -0,0 +1,182 @@
+# Editorial typography hierarchy craft rules
+
+Extends `typography.md` + `typography-hierarchy.md`. Defines hierarchy
+behavior for editorial surfaces: long-form articles, magazine layouts,
+digital guides, editorial landing pages, and blog posts.
+
+> Opt in via `od.craft.requires: [typography, typography-hierarchy, typography-hierarchy-editorial]`.
+
+---
+
+## What "editorial" means here
+
+Editorial hierarchy means the pacing is authored the way a print art director
+paces a spread: entry point, tension, rest, disruption, resolution. The reader
+is moved through content rather than given a uniform reading surface. SaaS
+hierarchy is additive — elements stack and each gets its turn. Editorial
+hierarchy is compositional — elements are weighted against each other and
+some are deliberately suppressed so others can breathe.
+
+---
+
+## Editorial hierarchy principles
+
+### 1. Dramatic scale jumps
+
+Editorial type scales are not gradual. The gap between display and body
+is large — often 3–5× — because the display element is not just a heading,
+it is a visual event.
+
+| Level | Typical range | Notes |
+|---|---|---|
+| Display / lede | 56–96 px | (editorial override) May intentionally exceed the default `typography.md` display range |
+| Deck / standfirst | 18–24 px | Large jump down — intentional |
+| Body | 16–18 px | Close to deck is fine; they're in the same reading register |
+| Pull quote | 28–40 px | Disrupts body rhythm; treated as a visual break, not a heading |
+| Caption / label | 11–13 px | Minimal — never competes with body |
+
+The gap between display and deck is the editorial signature. A small step
+here reads as SaaS, not editorial.
+
+### 2. Whitespace carries hierarchy
+
+Editorial hierarchy is not announced by a heavy heading. It is created by
+the space that surrounds an element. An article title in a moderate weight
+surrounded by generous whitespace outranks a bold heading crammed against
+its content.
+
+Rules:
+- Above-the-fold display element: minimum 2× the line-height in space above
+  and below before body begins.
+- Pull quotes: full column margin on both sides, or break the grid entirely.
+- Section breaks: use space as the default hierarchy signal. Separators (rules, dingbats,
+  folios, chapter marks) are allowed only when they reinforce publication identity or
+  distinguish unrelated content. For RTL layouts, mirror or adapt separators using
+  logical directions (inline-start, inline-end) rather than physical (left, right).
+- Caption clusters: tighter internal spacing, larger gap from the body above.
+
+### 3. Restrained bold
+
+Editorial systems use weight sparingly. The display element is often set in
+a light or regular weight — hierarchy is carried by scale and space, not mass.
+
+Bold in editorial context means: this word/phrase matters beyond the sentence.
+It is not used for section labels, UI chrome, or navigation. One to two bold
+phrases per 400 words of body copy is a working upper bound.
+
+If everything important is bold, nothing is.
+
+### 4. Display tracking
+
+Negative tracking at large sizes is mandatory for Latin display. At editorial display sizes
+(56 px+), tracking should be `-0.02em` to `-0.05em` (editorial override;
+see `typography.md` §letter-spacing for the default range). Light display
+weights may go tighter within this range.
+
+**Script-aware exception:** For Arabic, Persian, and Urdu (cursive-joining scripts),
+keep tracking at `0` — negative letter-spacing breaks cursive joining (see `rtl-and-bidi`).
+Hebrew uses logical spacing rules but is not cursive-joining; consult `rtl-and-bidi`
+for right-to-left baseline adjustments. Hierarchy in these scripts is carried by size,
+weight, and whitespace, not tracking.
+
+---
+
+### 5. Pull quotes as rhythm disruption
+
+A pull quote is not a blockquote. It is a visual interrupt.
+
+| Property | Behavior |
+|---|---|
+| Scale | 28–40 px — above body, below display |
+| Weight | Regular or light — never bold |
+| Tracking | Slightly negative (`-0.01em`) or zero |
+| Alignment | Break from body column — full width, or offset inline-start/inline-end |
+| Spacing | Large above and below — equal to or greater than a section break |
+| Color | May use `var(--accent)` as the only accent use on the page |
+
+Pull quotes placed at regular intervals destroy their effect. One per
+long-form article is usually correct. Two is a maximum.
+
+### 6. Body measure and reading rhythm
+
+Long-form body copy: 60–70 ch line length. Tighter than the `typography.md`
+max because editorial reading is sustained, not scanning.
+
+Line height: `1.6`–`1.7` for serif body. Slightly more generous than the
+universal rule because editorial bodies are set at a reading size, not a UI
+size.
+
+Do not justify. Use `text-align: start` with a ragged inline-end edge — the
+natural setting for editorial body copy on screen.
+
+### 7. Asymmetrical rhythm
+
+Uniform section spacing reads as a template. Editorial pacing alternates
+between compression and expansion:
+
+- Dense section → spacious section → medium section.
+- A tightly spaced image caption cluster immediately after a generous
+  body paragraph creates productive tension.
+- The final section before a pull quote should tighten; after it, release.
+
+---
+
+## Editorial hierarchy table
+
+| Element | Scale | Weight | Tracking | Leading | Spacing role |
+|---|---|---|---|---|---|
+| Display headline | 56–96 px | Light or regular | `-0.02em` to `-0.05em` | `1.0`–`1.1` | Event — generous above/below |
+| Deck / standfirst | 18–24 px | Regular | `0` | `1.4`–`1.5` | Transitional — moderate gap below |
+| Byline / dateline | 12–14 px | Regular or medium | `0.02em`–`0.04em` | `1.5` | Recedes — tight gap below |
+| Body | 16–18 px | Regular | `0` | `1.6`–`1.7` | Baseline — rhythm carrier |
+| Pull quote | 28–40 px | Regular or light | `-0.01em` (Latin only; 0 for joining scripts) | `1.2`–`1.3` | Interrupt — large above/below |
+| Image caption | 12–13 px | Regular | `0.01em` | `1.5` | Recedes — tight cluster |
+| Section label | 11–12 px | Medium | `0.06em`–`0.1em` (if caps) | `1.5` | Wayfinding only |
+
+---
+
+## Anti-patterns
+
+- **Bold display headline** — editorial display is usually light or regular.
+  Bold display reads as billboard advertising. If the design system's display
+  weight is heavy, either use the regular cut or revisit the choice.
+- **Uniform section padding** — every section has the same gap. No pacing.
+  The page reads as a list of content blocks.
+- **Pull quote styled as a callout box** — border-left, background tint,
+  or card treatment. A pull quote is typographic. It does not need a container.
+- **Deck set at body size** — the gap between headline and deck must be large
+  enough to read as a scale event. 18 px minimum for a deck below a 56 px+
+  headline.
+- **Heading for every section** — editorial long-form does not require
+  a heading at every content shift. Space and pacing are allowed to do the
+  work. (guidance)
+- **Positive tracking on display** — wide-tracked display headlines read as
+  a branding exercise. Tighten them.
+- **UI chrome in the reading column** — buttons, tags, chip badges interrupting
+  prose flow inside the body text column. Functional controls (inline code-copy,
+  API anchors, callout toggles) may live inside code and API blocks, but decorative
+  badges and UI chrome should live outside the reading measure to keep prose focus clear.
+
+---
+
+## Lint
+
+- [ ] Display headline is light or regular weight unless the design system
+      specifies otherwise.
+- [ ] Display tracking is within `-0.02em` to `-0.05em` at 56 px+ (Latin only;
+      0 for Arabic/Persian/Urdu joining scripts; see `rtl-and-bidi` for Hebrew). (guidance)
+- [ ] Pull-quote tracking: `-0.01em` (Latin only; 0 for joining scripts). (guidance)
+- [ ] Gap between display and deck: display/deck ratio ≥ 1.5× or absolute px delta
+      ≥ 24 px to read as a scale event. (guidance)
+- [ ] Body line height is `1.6`–`1.7`.
+- [ ] Body measure is 60–70 ch.
+- [ ] Pull quote, if present, breaks the body column (full width or offset).
+- [ ] No more than 2 pull quotes in a single article surface. (long-form only)
+- [ ] Section spacing alternates — one gap ≥ 1.5× baseline rhythm while another
+      is ≤ 1.2×. (long-form only — guidance)
+- [ ] Bold used ≤ 2 times per 400 words in body copy. (long-form only)
+- [ ] `var(--accent)` used ≤ 2 times on the full editorial surface (see `color.md` §accent discipline).
+- [ ] Section separators (rules, dingbats) are used only when they
+  reinforce publication identity or clearly mark unrelated-content boundaries;
+  they must not be used as a hierarchy fallback. (guidance)
+- [ ] Pull quote has no background, border, or container treatment.

package/dist/assets/design/craft/typography-hierarchy.md

@@ -0,0 +1,165 @@
+# Typography hierarchy craft rules
+
+Shared hierarchy contracts that layer on top of `typography.md`. This file does
+not repeat scale ranges or tracking values — those live in `typography.md`.
+This file defines how hierarchy *behaves*: entry points, rhythm, tension, and
+the conditions under which controlled violations are allowed. This contract
+applies per-surface (a page with multiple pacing resets may establish new
+primaries at intentional intervals), not globally.
+
+> Opt in via `od.craft.requires: [typography, typography-hierarchy]`.
+> Aesthetic-specific variants (e.g. `typography-hierarchy-editorial`) extend this.
+
+---
+
+## The core contract
+
+Every typographic surface must satisfy all three:
+
+1. **One dominant entry point.** The eye needs a place to start. One element
+   wins the hierarchy — not two, not three. If everything competes, nothing leads.
+2. **Intentional rhythm between levels.** Hierarchy is not a list of sizes.
+   It is the *contrast* between them. Adjacent levels that are too close
+   in scale, weight, or spacing produce a flat, undifferentiated surface.
+3. **Recoverable information flow.** Hierarchy may be inverted, collapsed,
+   or disrupted — but a reader must still be able to reconstruct the content
+   structure without re-reading. If they can't, it's chaos, not tension.
+
+---
+
+## Hierarchy vectors
+
+Scale is one lever. Use all five.
+
+| Vector | What it controls | Hierarchy direction |
+|---|---|---|
+| Scale | Size contrast between levels | Large → small reads as primary → secondary |
+| Weight | Mass contrast between levels | Heavier reads as primary (see Controlled violations for weight inversion) |
+| Spacing | Breathing room around an element | More space = more visual importance |
+| Tracking | Tension and velocity | Tighter = faster; wider = ceremonial, slower |
+| Alignment | Relationship to the grid/edge | Breaking alignment signals importance |
+
+No single vector is required. A heading may lead through spacing alone if
+scale is deliberately suppressed. A pull quote may lead through alignment
+break. Identify which vectors are active and make sure at least two are
+working in the same direction for the dominant element.
+
+---
+
+## Semantic role ≠ visual role
+
+Allowed. Not an error. Not a lint violation.
+
+An `<h1>` may render visually quieter than a nearby `<p>` if the
+composition requires it. Body copy may behave like display typography.
+A label may visually outrank a heading.
+
+**The condition:** information flow must remain intact. A user who reads
+linearly must still understand what is important, what supports it, and
+what is incidental — regardless of which element "wins" visually.
+
+---
+
+## Hierarchy rhythm — the two failure modes
+
+### Flat hierarchy
+
+Everything lands at roughly the same visual weight. The surface reads as
+a wall. Usually caused by:
+- Scale steps that are too close (e.g. 18 / 20 / 22 px for three levels)
+- Weight used only once (everything is regular, or everything is medium)
+- Uniform spacing between all elements
+
+Fix: increase contrast between levels. Use at least two vectors simultaneously.
+
+### Noise hierarchy
+
+Too many elements fighting for dominance. Everything is bold, large, or
+accented. The eye has no resting point and no path.
+
+Fix: promote one element deliberately. Demote everything else — including
+things that feel important. Hierarchy is relative, not absolute.
+
+---
+
+## Controlled violations
+
+The following are explicitly allowed when the three core contracts are met:
+
+| Violation | Allowed when |
+|---|---|
+| Body copy at display scale | It is the intended entry point and nothing else competes |
+| Heading rendered lighter than body | Intentional visual inversion with intact information flow |
+| Zero scale contrast between levels | Hierarchy is carried entirely by spacing or tracking |
+| No heading-level element visible | Hierarchy is emergent from layout/spacing alone |
+| Primary-level spacing applied to secondary element | Creates deliberate tension while maintaining information flow |
+
+**"Information flow remains intact" safeguards:**
+- DOM/reading order still matches content meaning (no layout inversion breaks narrative)
+- Proximity groups the inverted element with its parent/context
+- Only one primary exists in the visual region (no competing co-primaries)
+- A quick scan can identify entry point / support / incidental roles without rereading
+
+---
+
+## Spacing as hierarchy
+
+Spacing is a full hierarchy vector. A typographic level can be elevated
+entirely through surrounding whitespace without changing its size or weight.
+
+Rules:
+- Space above an element signals its relationship to what came before.
+- Space below an element signals its relationship to what follows.
+- An isolated element with large surrounding space reads as display-level
+  regardless of its font size.
+- Uniform spacing between all elements destroys spatial hierarchy.
+
+---
+
+## Three-level working model
+
+Most surfaces can be mapped to three functional levels:
+
+| Level | Role | Typical vectors |
+|---|---|---|
+| **Primary** | Entry point. One at a time per visual region; long-form surfaces may re-establish at intentional pacing resets. | Scale, spacing, or alignment break |
+| **Secondary** | Structure. Subdivides or supports primary. | Weight, scale step, or tracking shift |
+| **Tertiary** | Incidental. Labels, captions, metadata. | Scale reduction, weight reduction, or positive tracking |
+
+More than three visible levels above the fold is usually a composition problem,
+not a hierarchy opportunity. Collapse or demote before adding a fourth level.
+
+**Long-form surfaces:** May re-establish a primary at intentional pacing resets
+(e.g. a new section with its own headline and breathing room). Never maintain
+two simultaneous primaries within the same visual region.
+
+---
+
+## Anti-patterns
+
+- **Graduated weight ladder** — regular → medium → semibold → bold → extrabold,
+  each level one step heavier. Reads as a default scale, not authored hierarchy.
+  Weight should jump, not step.
+- **Uniform section spacing** — every section gap is the same value. No
+  hierarchy information is carried by spacing. Vary it deliberately.
+- **Heading as the only hierarchy vector** — the heading is large and bold;
+  everything else is flat. The heading does all the work. This is a sign
+  that spacing and tracking are not being used as vectors.
+- **Symmetrical emphasis** — two elements receive equal visual weight as
+  co-primaries. Pick one. The other becomes secondary.
+- **Size-only hierarchy** — all contrast is in font size alone. Weight,
+  spacing, tracking, and alignment are uniform across levels. Fragile —
+  any layout constraint that collapses the size contrast destroys the hierarchy.
+
+---
+
+## Lint
+
+- [ ] One element is unambiguously dominant above the fold.
+- [ ] At least two hierarchy vectors are active on the dominant element.
+- [ ] No two adjacent levels share the same scale, weight, AND spacing.
+- [ ] Spacing between levels varies — at least one gap is ≥1.5× the others or
+      represents one typographic scale step (e.g. one token unit like `gap-md` vs `gap-sm`). (guidance)
+- [ ] Semantic/visual role inversions remain structurally readable.
+- [ ] Flat hierarchy: scale steps between levels are ≥1.25× apart OR compensated by a weight or spacing jump. (guidance)
+- [ ] Noise hierarchy: no more than one element reads as primary above the fold.

package/dist/assets/design/craft/typography.md

@@ -0,0 +1,122 @@
+# Typography craft rules
+
+Universal typography rules that apply on top of any `DESIGN.md`. The
+active design system decides *which* fonts; this file decides *how* they
+behave at every size.
+
+> Adapted from [refero_skill](https://github.com/referodesign/refero_skill)
+> (MIT) — distilled and re-tuned for OpenDesign's token system.
+
+## Type scale
+
+Use a multiplicative scale (1.2 or 1.25). Cap at 6–8 sizes per artifact.
+
+| Role | Range |
+|---|---|
+| Display | 48–72 px |
+| H1 | 32–48 px |
+| H2 | 24–32 px |
+| H3 | 20–24 px |
+| Body | 15–18 px |
+| Small | 13–14 px |
+| Caption | 11–12 px |
+
+## Line height (leading)
+
+| Text size | Line height |
+|---|---|
+| Display / H1 (≥32 px) | `1.0`–`1.2` (tight) |
+| Body (15–18 px) | `1.5`–`1.6` |
+| Small (≤14 px) | `1.5` |
+
+### CJK overrides — these are not optional
+
+The table above is Latin leading. Latin display type can go to `1.0`
+because the ascender/descender slack inside the em box keeps lines
+apart. **CJK glyphs fill the em box**, so the same value makes
+consecutive lines touch, and multi-line Chinese headlines visibly
+collide.
+
+| Text size | Latin | CJK |
+|---|---|---|
+| Display / H1 (≥32 px) | `1.0`–`1.2` | **`1.3`–`1.4`** |
+| Body (15–18 px) | `1.5`–`1.6` | `1.7`–`1.8` |
+
+The CJK floor has **no upper size tier**. It applies to every heading
+level, including the **cover / hero main title** — the single biggest
+headline on a deck's first slide. A Chinese cover title at 72 px,
+96 px, or larger, especially one split into multiple lines with
+`<br>`, is still CJK display text: set `line-height: 1.3`–`1.4` on
+it, never the Latin `1.0`–`1.2`. At 96 px a `1.05` leading makes the
+two lines of a Chinese cover headline visibly collide. This is the
+single most common violation, so check the cover main title first.
+
+Negative tracking is Latin-only for the same reason: CJK is already
+set on a fixed em grid, so `-0.02em` on a Chinese headline crowds the
+glyphs instead of tightening the word. Use `0` for CJK display text.
+
+When one artifact mixes both — an English kicker over a Chinese
+headline is the common case — set the tight Latin values on the Latin
+element only. Do not inherit them onto the CJK block from a shared
+parent rule.
+
+## Letter-spacing — the rule that makes or breaks craft
+
+This is the single most-skipped rule in AI-generated design. **No
+exceptions.**
+
+| Context | Letter-spacing |
+|---|---|
+| Body text (14–18 px) | `0` (default) |
+| Small text (11–13 px) | `0.01em` to `0.02em` (positive) |
+| UI labels and button text | `0.02em` |
+| **ALL CAPS** | **`0.06em` to `0.1em` (required)** |
+| Headings 32 px+ | `-0.01em` to `-0.02em` |
+| Display 48 px+ | `-0.02em` to `-0.03em` |
+
+ALL CAPS without positive tracking looks cramped and amateur. Display
+text without negative tracking looks loose and weak. These two failures
+are the most reliable AI-slop tells.
+
+The `0.06em` floor is not arbitrary: it is the empirical lower bound
+that print and web typographers have converged on for uppercase
+tracking (cf. Bringhurst's *Elements of Typographic Style* §3.2.7,
+which recommends 5–10% of the em for caps; modern screen practice
+rounds the lower end to 0.06em). Anything tighter and the counters
+collide on screen; the upper bound `0.1em` keeps the word from
+disintegrating into letters.
+
+## Font pairing
+
+- Maximum 2 typefaces per artifact (display + body, or one variable face
+  used at multiple weights).
+- Always declare a system fallback chain. If the active `DESIGN.md`
+  ships a webfont URL, the fallback must still produce a coherent look.
+- Never set `font-family: system-ui` alone on a heading — that is the
+  textbook AI default; always pair it with an intentional first choice.
+
+## Line length
+
+Limit body copy to **50–75 characters** per line. In CSS:
+`max-width: 65ch` is a safe default.
+
+## Three-weight system
+
+Most well-crafted UIs use exactly 3 weights:
+- **Read** (400 / 450) — body copy
+- **Emphasize** (510 / 550) — UI text, labels, navigation
+- **Announce** (590 / 600) — headlines, buttons
+
+Weight 700+ is rarely needed. If your design uses bold for "emphasis on
+emphasis," it likely lacks weight discipline elsewhere.
+
+## Common mistakes (lint these)
+
+- ALL CAPS without `letter-spacing` ≥ `0.06em`.
+- Display text (≥32 px) without negative tracking (Latin only — see the CJK overrides).
+- CJK display text at Latin leading (`≤1.2`), which makes the lines overlap.
+- Multi-line CJK cover / hero titles (72–96 px+, e.g. split with `<br>`) below `1.3` line-height.
+- Negative tracking applied to CJK text.
+- More than 3 type sizes visible above the fold.
+- Mixed serif and slab on the same screen without a clear role split.
+- Body copy in `text-align: justify` (creates rivers; never use on the web).

package/dist/assets/design/react-bits/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: react-bits
+description: >
+  Use when a React interface needs an animated component — a text reveal, a shader-like background, an
+  interactive card, a marquee or a counter — and the work should be taken from React Bits rather than
+  written from scratch. Covers the two-step fetch through the reactbits tool, the components' licence
+  boundary (use in an application is permitted, redistribution of the components is not), the four
+  variants and how to name them, the integration contract (the missing `'use client'` directive, extra
+  stylesheets, exact dependency ranges, WebGL and SSR hazards) and the quality bar for motion
+  (`prefers-reduced-motion`, layout properties, listener and frame-loop cleanup). Also use it when
+  reviewing a component that was already added, or when deciding whether an effect earns its bundle
+  cost at all.
+---
+
+# React Bits components
+
+React Bits is an upstream library of animated React components — text animations, backgrounds, cards,
+and micro-interactions — published as a shadcn-style registry rather than as a package. This skill
+covers how to get one into a project correctly, and when not to.
+
+## 1. Licence first, because it decides the shape of everything else
+
+Upstream's `LICENSE.md` is MIT **plus the Commons Clause**. The two sentences that matter:
+
+- **Use is permitted.** Putting a component in your application — including a commercial one — and
+  modifying it there is what the licence is for.
+- **Redistribution is not.** Selling, sublicensing, or redistributing the components themselves —
+  alone, in a bundle, or as a ported version — is forbidden.
+
+So: the component's source **belongs in the user's project, never in this package.** Nothing in this
+pack vendors it, caches it to disk, or re-spells it as a local port. `THIRD_PARTY_NOTICES.md` records
+this position. If a request is effectively "add React Bits to our product so users get these
+components", that is redistribution, and the answer is no — the components have to be pulled into the
+consumer's own project, by the consumer.
+
+## 2. Three steps, one tool
+
+`freecodego_reactbits` has three actions, and they are meant to be used in order.
+
+1. `search` — a keyword (a component name, an effect like `blur`, a dependency like `gsap`) matched
+   against upstream's index. Returns names, descriptions, exact dependency ranges and file paths. No
+   source. Variants of one component are folded into one row, so four near-identical rows do not bury
+   the description you are deciding on.
+2. `get` — one variant's files **with their contents**, plus the integration review described below.
+   Takes a component name, a registry variant name, or a docs slug; `language` defaults to `ts` and
+   `style` to `tailwind`, and every other published variant is listed in the result so you can ask
+   for a different one. Use this when the caller wants to read the code, place it by hand, or review it
+   before deciding.
+3. `apply` — write that variant into a directory the caller names. **Requires both `directory` (relative
+   to the session working directory) and `confirm: true`**; without the confirmation the call is refused
+   and the refusal lists every path it would have written, which is the moment to check the destination
+   and the variant. It writes only the files upstream publishes, never overwrites an existing file unless
+   `if_exists: "replace"` was asked for, and reports every file it wrote, skipped or failed on.
+
+Two mechanical alterations, and nothing else, are made by `apply`, and both are listed per file in the
+result so a diff can be audited:
+
+- **A leading `'use client'`.** Off under `client_directive: "never"`, forced on with `"always"`, and on
+  by default (`"auto"`) exactly where the review calls it blocking — a server-rendering framework, or one
+  the caller did not name. It cannot change what the component renders.
+- **A bounded-motion block** appended to a stylesheet that animates and ignores the system setting, unless
+  `reduced_motion: false`. It sets `animation-duration`/`transition-duration` to `0.01ms` rather than
+  removing the animation, because an entrance animation that starts at `opacity: 0` would otherwise leave
+  content permanently invisible — the patch would hide the page it was meant to make calmer.
+
+Nothing is installed. Dependencies come back as exact ranges for the project's own package manager, and
+any motion the JavaScript drives is left to the caller: the result's `followUps` says so rather than
+pretending a stylesheet rule could reach it.
+
+## 3. Names, and how the registry spells them
+
+| Surface | Spelling | Example |
+| --- | --- | --- |
+| Registry variant | `<Component>-<LANG>-<STYLE>` | `CountUp-TS-TW` |
+| Registry index | the same, one row per variant | `CountUp-TS-TW`, `CountUp-TS-CSS`, … |
+| Docs page slug | kebab-case, not mechanical | `ascii-text` for `ASCIIText` |
+
+A component has four variants: `JS`/`TS` × `CSS`/`TW`. `TW` means Tailwind classes; `CSS` means the
+component carries its own stylesheet, which `apply` writes beside the component and `get` reports as a
+second file. Prefer `TS`/`TW` when the project already uses Tailwind and shadcn, which is the ecosystem this
+registry is built for; prefer `CSS` when it uses plain CSS or CSS modules.
+
+## 4. The integration contract
+
+The `get` result carries a review — findings with a `severity` — and these are the ones that decide
+whether the copy works at all:
+
+- **`'use client'`.** Upstream's components do not carry the directive, and most of them need it:
+  they register animation plugins, read layout in an effect, attach pointer listeners, or observe
+  elements. Under a server-rendering framework this is a build or first-render failure. Add it as the
+  file's first line.
+- **Extra files.** A `CSS` variant's stylesheet has to be written and imported, or the component
+  renders unstyled.
+- **Local imports.** The review lists specifiers that are neither React nor a package. Those are files
+  you place — fetch the sibling component with the same tool rather than inventing a path.
+- **Dependencies.** Install the exact ranges the result reports (`motion@^12.23.12`,
+  `gsap@^3.13.0`, …) with the project's own package manager — and use the project's, because a tool
+  that picked one would be guessing. Some manifests are heavy (`three`, `@react-three/fiber`,
+  `postprocessing`, `matter-js`); that cost is a design decision, not a detail.
+
+## 5. Motion quality bar
+
+These are the things that make a component a liability rather than an asset:
+
+- **Honour the system setting.** Many upstream components have no `prefers-reduced-motion` branch.
+  Add one, or the effect cannot be turned off by the people who need it off.
+- **Do not animate layout properties.** `transform` and `opacity` are what the compositor can handle;
+  animating `height`, `top`, or `margin` forces layout every frame. This package's own detector has a
+  rule for it (`layout-transition`), and a component that trips it will be flagged in review.
+- **Clean up.** Remove listeners, cancel frame loops, and disconnect observers on unmount. A leaked
+  loop keeps running in a background tab and shows up as a fan that never stops.
+- **WebGL renders blank, not broken.** Shader and canvas components produce an empty area when the
+  context is unavailable, with no error. Verify on the target machine rather than trusting it, and
+  keep content that matters outside the canvas.
+- **One effect, not three.** A page with an animated background, an animated heading, and an animated
+  card has three competing focal points and none. Pick the one that serves the message.
+
+## 6. When not to use it
+
+React Bits is the wrong tool for content-first products, dense data interfaces, and flows where the
+user is completing a task rather than being impressed — an animated background behind a settings
+screen costs a bundle and buys nothing. If the interface's job is reading, arguing, or transacting,
+plain typography and spacing do more than any shader.
+
+## 7. Cross-check before you ship
+
+Run the fetched code past this pack's own rules — `freecodego_design_detect` on the file after it has
+been placed — and look for the standing conflicts: bounce easings, gradient-clipped text, and layout
+animation. The `get` result already names which of them the source would trip, so the cheap moment to
+decide is before the code is written.