@once-ui-system/core 1.7.10 → 1.7.12

package/dist/ai/eval-tasks.md

@@ -0,0 +1,71 @@
+# Once UI — AI generation eval suite
+
+Fixed prompt set for measuring harness effectiveness. Run each task with and
+without the harness (rules.md + spec.json), ideally across two models, and
+score with the checklist below. Add a regression task whenever a new pitfall
+is found in the wild.
+
+## Tasks
+
+1. **Analytics dashboard** — KPI stat cards (trend indicators), a line chart, a bar chart, recent-activity list. Tests: data components, `CountFx`, grid responsiveness.
+2. **Settings page** — sidebar sections, profile form (avatar upload, inputs, selects), danger zone. Tests: form controls, `MediaUpload`, surface recipes.
+3. **Pricing page** — three tiers, highlighted middle tier, feature comparison table, FAQ accordion. Tests: `Card`, `Badge`, `Table`, `Accordion`, proportional emphasis.
+4. **Chat UI** — message list with avatars, streaming indicator, input bar with emoji picker, command palette hint. Tests: `EmojiPickerDropdown`, `Kbd`, `Spinner`, scroll containers.
+5. **Marketing hero** — headline with text effect, CTA pair, social proof logos, background effect. Tests: effects usage (`LetterFx`/`TypeFx`/`RevealFx`, `Background`/`MatrixFx`/`BlobFx`), restraint.
+6. **Auth flow** — login with password + OTP step in a stacked dialog. Tests: `Dialog` `stack`, `OTPInput`, `PasswordInput`, validation states.
+7. **E-commerce product card grid** — image, price, tag, hover actions, skeleton loading state. Tests: `Card`, `Media`, `Skeleton`, `Tag`, hover patterns.
+8. **Onboarding checklist** — progress bar, step list with status indicators, celebratory completion. Tests: `ProgressBar`, `StatusIndicator`, `CelebrationFx`.
+9. **Data table page** — sortable table, filters row (segmented control, date range, search), pagination. Tests: `Table`, `SegmentedControl`, `DateRangePicker`, toolbar composition.
+10. **User profile popover** — avatar trigger, `UserMenu`/`HoverCard` with stats and actions. Tests: overlay components, `AvatarGroup`.
+11. **Changelog/timeline page** — versioned entries on a `Timeline`, tags per release, copyable code snippets. Tests: `Timeline`, `CodeBlock`, `InlineCode`.
+12. **Feedback widget** — floating trigger, dialog with rating chips, textarea, toast on submit. Tests: `Chip` selection, `useToast`/`Feedback`, positioning.
+
+## Scoring checklist (per task)
+
+Mechanical (count occurrences):
+
+- [ ] Compiles / no invented props or components
+- [ ] Redundant-default props (`position="relative"`, `variant="primary"` on Button, ...) — target: 0
+- [ ] Shorthand violations (`fillWidth fillHeight` instead of `fill`, `horizontal+vertical center` instead of `center`, `Flex direction=` instead of `Row`/`Column`) — target: 0
+- [ ] `style={{}}` uses where a token prop exists — target: 0
+- [ ] Raw HTML elements where a component exists (`img`, `a`, `button`) — target: 0
+- [ ] Hex/rgb colors — target: 0
+- [ ] Distinct Once UI components used — higher is better (task-appropriate)
+
+Judgment (1–5):
+
+- [ ] Proportionality: spacing rhythm, type scale, surface hierarchy look like real Once UI
+- [ ] Component appropriateness: purpose-built components chosen over generic primitives
+- [ ] Responsiveness: breakpoint props used where layout should adapt
+- [ ] Restraint: effects enhance rather than dominate
+
+## Pitfall log
+
+Record every recurring failure here; each entry should become a rule in
+`rules.md` or a gold example, plus stay in this list as a regression check.
+
+| Date | Pitfall observed | Fix applied |
+|------|------------------|-------------|
+| 2026-06-12 | `position="relative"` written despite being default | rules.md #3 |
+| 2026-06-12 | `fillWidth fillHeight` instead of `fill` | rules.md #2 |
+| 2026-06-12 | `horizontal="center" vertical="center"` instead of `center` | rules.md #2 |
+| 2026-06-12 | Only ~10 common components used, defaults only | rules.md #12–13 |
+| 2026-06-12 | Section gaps too small (48), page feels cramped | rules.md #17 |
+| 2026-06-12 | Section headings too small (`heading-strong-m`), hero undersized | rules.md #18 |
+| 2026-06-12 | Testimonial quote (BlockQuote default) larger than section title | rules.md #19 |
+| 2026-06-12 | Identical centered heading+subtitle on every section (dated); Tag+sparkle eyebrow | rules.md #20 |
+| 2026-06-12 | Absolute Background missing `top="0" left="0"` → offset by parent padding | rules.md #21, recipes.md |
+| 2026-06-12 | Gradient `width: 500` (125% of container); units misunderstood | rules.md #22 |
+| 2026-06-12 | `brand-background-weak` glow at `opacity: 30` — invisible vs page | rules.md #23, recipes.md |
+| 2026-06-12 | `RevealFx delay={index * 80}` (seconds!) and `translateY={16}` (16rem!) | rules.md #24, recipes.md #7 |
+| 2026-06-12 | `LogoCloud` without `columns` → single-column stack | rules.md #25 |
+| 2026-06-12 | No decorative components used beyond one gradient; flat result | recipes.md + rules.md #26 |
+| 2026-06-12 | RevealFx on every section (dated, eye-grabbing); mount-timed animations finish off-screen | rules.md #27–29, recipes.md #7 |
+| 2026-06-12 | Hero gradient clipped: ambient layer inside narrow `maxWidth` container with `overflow="hidden"` | rules.md #21b, recipes.md #1 |
+| 2026-06-12 | Reveal on hero text fragments + lone highlighted card (incoherent grouping) | rules.md #28b |
+| 2026-06-12 | `Card` used for static panels (tiers, testimonials, stats) | rules.md #12 |
+| 2026-06-12 | Arbitrary `maxWidth` numbers; no container-width convention | rules.md #15 |
+| 2026-06-12 | Design intent (style/layout/color/decoration/imagery) guessed instead of asked | rules.md "Before you build" |
+| 2026-06-12 | Invented icon names (`more`, `bell`, `arrowRight`) | rules.md #14b, IconName list in spec.json |
+| 2026-06-12 | `Badge title` + children rendered same text twice ("2 unread2") | rules.md #14c |
+| 2026-06-12 | `Fade` wrapped the whole message list → washed-out content | rules.md #14d |

package/dist/ai/examples/blocks/manifest.json

@@ -0,0 +1,191 @@
+{
+  "version": 1,
+  "description": "Once UI Pro block references for agent codegen — canonical composition patterns at production quality. Reference-only; not all blocks are runnable standalone.",
+  "usage": "Load the block matching your task intent. Mimic structure and prop patterns; adapt data and copy.",
+  "blocks": [
+    {
+      "id": "Header1",
+      "file": "Header1.tsx",
+      "title": "App header with MegaMenu + Kbar",
+      "tags": ["navigation", "header", "marketing"],
+      "components": ["MegaMenu", "MobileMegaMenu", "Kbar", "Logo", "UserMenu", "NavIcon", "SmartLink"],
+      "patterns": ["sticky header", "mega menu sections with featured links", "command palette ⌘K"],
+      "tasks": ["marketing-hero", "dashboard"],
+      "standalone": true
+    },
+    {
+      "id": "Header2",
+      "file": "Header2.tsx",
+      "title": "Minimal marketing header",
+      "tags": ["navigation", "header", "marketing"],
+      "components": ["Logo", "Row", "Button", "SmartLink"],
+      "tasks": ["marketing-hero"],
+      "standalone": true
+    },
+    {
+      "id": "Header3",
+      "file": "Header3.tsx",
+      "title": "Streaming/media header",
+      "tags": ["navigation", "header", "streaming"],
+      "components": ["Logo", "IconButton", "UserMenu"],
+      "tasks": ["streaming"],
+      "standalone": true
+    },
+    {
+      "id": "Header4",
+      "file": "Header4.tsx",
+      "title": "Compact docs-style header",
+      "tags": ["navigation", "header", "docs"],
+      "components": ["Logo", "UserMenu", "ToggleButton", "SmartLink"],
+      "tasks": ["settings"],
+      "standalone": true
+    },
+    {
+      "id": "Footer1",
+      "file": "Footer1.tsx",
+      "title": "Minimal footer bar",
+      "tags": ["footer"],
+      "components": ["Row", "IconButton", "Text"],
+      "standalone": true
+    },
+    {
+      "id": "Footer2",
+      "file": "Footer2.tsx",
+      "title": "Footer with CTA",
+      "tags": ["footer", "marketing"],
+      "components": ["Column", "Button", "SmartLink"],
+      "standalone": true
+    },
+    {
+      "id": "Footer3",
+      "file": "Footer3.tsx",
+      "title": "Multi-column sitemap footer",
+      "tags": ["footer", "marketing"],
+      "components": ["Grid", "SmartLink", "Tag", "Logo", "IconButton"],
+      "patterns": ["5-column nav grid with responsive collapse"],
+      "tasks": ["marketing-hero"],
+      "standalone": true
+    },
+    {
+      "id": "Footer4",
+      "file": "Footer4.tsx",
+      "title": "Premium footer with TypeFx + Particle",
+      "tags": ["footer", "marketing", "effect"],
+      "components": ["Background", "Particle", "TypeFx", "Mask", "Avatar", "Tag"],
+      "patterns": ["animated wordmark", "particle decoration", "masked gradient"],
+      "tasks": ["marketing-hero"],
+      "standalone": true
+    },
+    {
+      "id": "Waitlist1",
+      "file": "Waitlist1.tsx",
+      "title": "Waitlist / coming-soon hero",
+      "tags": ["marketing", "hero", "waitlist"],
+      "components": ["RevealFx", "CountFx", "AvatarGroup", "Input", "Badge", "Background"],
+      "patterns": ["custom cursor SVG", "subscriber count animation", "email capture with validation"],
+      "tasks": ["marketing-hero"],
+      "related": ["Background6.tsx"],
+      "standalone": true
+    },
+    {
+      "id": "Dashboard1",
+      "file": "Dashboard1.tsx",
+      "title": "Full analytics dashboard shell",
+      "tags": ["dashboard", "data"],
+      "components": ["Card", "LineChart", "Grid", "Scroller", "StatusIndicator", "Table1"],
+      "patterns": ["StatCard with sparkline chart overlay", "activity feed with Card rows", "orders table"],
+      "tasks": ["dashboard"],
+      "compose": ["Sidebar1.tsx", "Header1.tsx", "Table1.tsx"],
+      "standalone": false
+    },
+    {
+      "id": "Table1",
+      "file": "Table1.tsx",
+      "title": "Data table with search, pagination, selection",
+      "tags": ["data", "dashboard", "table"],
+      "components": ["Input", "Checkbox", "DropdownWrapper", "CountFx", "IconButton", "ToggleButton"],
+      "patterns": ["custom render columns", "selectable rows", "items per page"],
+      "tasks": ["dashboard", "chat"],
+      "standalone": true
+    },
+    {
+      "id": "Chat1",
+      "file": "Chat1.tsx",
+      "title": "Three-pane chat layout",
+      "tags": ["chat", "layout"],
+      "components": ["SplitView pattern via Row", "Sidebar4", "Feed3", "Sidebar5", "Table1"],
+      "patterns": ["channel sidebar + feed + members panel", "view switching"],
+      "tasks": ["chat"],
+      "compose": ["Feed3.tsx", "Sidebar4.tsx", "Sidebar5.tsx"],
+      "standalone": false
+    },
+    {
+      "id": "Feed3",
+      "file": "Feed3.tsx",
+      "title": "Chat message feed + composer",
+      "tags": ["chat", "social"],
+      "components": ["Avatar", "Textarea", "EmojiPickerDropdown", "Media", "OgCard", "IconButton"],
+      "patterns": ["thread messages without bubbles", "attachment grid", "reactions row", "emoji picker prefix"],
+      "tasks": ["chat"],
+      "standalone": true
+    },
+    {
+      "id": "Sidebar4",
+      "file": "Sidebar4.tsx",
+      "title": "Chat channel sidebar",
+      "tags": ["chat", "sidebar", "navigation"],
+      "components": ["Scroller", "ToggleButton", "Fade", "Media", "Avatar"],
+      "patterns": ["cover image header with Fade strip", "grouped channel list", "user status footer"],
+      "tasks": ["chat"],
+      "standalone": true
+    },
+    {
+      "id": "Sidebar5",
+      "file": "Sidebar5.tsx",
+      "title": "Chat members panel",
+      "tags": ["chat", "sidebar"],
+      "components": ["Card", "Avatar", "DropdownWrapper", "Heading"],
+      "tasks": ["chat"],
+      "standalone": true
+    },
+    {
+      "id": "Roadmap1",
+      "file": "Roadmap1.tsx",
+      "title": "Kanban-style product roadmap",
+      "tags": ["roadmap", "content", "community"],
+      "components": ["Card", "StatusIndicator", "User", "Scroller"],
+      "patterns": ["horizontal column scroll", "Card for linked tasks / Column for static", "brand dot product header"],
+      "tasks": ["roadmap"],
+      "standalone": true
+    },
+    {
+      "id": "Streaming1",
+      "file": "Streaming1.tsx",
+      "title": "Video streaming page",
+      "tags": ["streaming", "media", "marketing"],
+      "components": ["Media", "Carousel", "ProgressBar", "Fade", "Scroller"],
+      "patterns": ["floating controls portal", "episode carousel", "hero video player"],
+      "compose": ["Header3.tsx", "Footer2.tsx"],
+      "standalone": false
+    },
+    {
+      "id": "Productivity1",
+      "file": "Productivity1.tsx",
+      "title": "Issue board / kanban productivity",
+      "tags": ["productivity", "dashboard"],
+      "components": ["Card", "AvatarGroup", "IconButton", "Scroller"],
+      "patterns": ["horizontal issue columns", "Card task items with avatars"],
+      "compose": ["Sidebar2.tsx"],
+      "standalone": false
+    }
+  ],
+  "byTask": {
+    "marketing-hero": ["Waitlist1", "Header1", "Footer4", "Footer3"],
+    "dashboard": ["Dashboard1", "Table1", "Header1", "Sidebar1"],
+    "chat": ["Chat1", "Feed3", "Sidebar4", "Sidebar5", "Table1"],
+    "settings": ["Header4", "Sidebar1"],
+    "pricing": ["Header2", "Footer2"],
+    "auth": ["Header2"],
+    "roadmap": ["Roadmap1"]
+  }
+}

package/dist/ai/gotchas.json

@@ -0,0 +1,85 @@
+{
+  "Background.gradient.width": {
+    "rule": "Quarter-percent units: 400 = 100% of container. Soft glows use width 100–200, not 500.",
+    "components": ["Background"]
+  },
+  "Background.gradient.x": {
+    "rule": "x/y are percent positions of the container (50/50 = center).",
+    "components": ["Background"]
+  },
+  "Background.absolute": {
+    "rule": "Every absolute decorative layer needs top=\"0\" left=\"0\" or it offsets by parent padding.",
+    "components": ["Background", "MatrixFx", "BlobFx"]
+  },
+  "Card.interactive": {
+    "rule": "Card is for interactive surfaces only (href or onClick). Static panels use Column + background=\"surface\" border=\"neutral-alpha-weak\" radius=\"l\".",
+    "components": ["Card"]
+  },
+  "Fade.edge": {
+    "rule": "Fade is an edge overlay strip on scroll containers, not a content wrapper.",
+    "components": ["Fade"]
+  },
+  "RevealFx.delay": {
+    "rule": "delay is in seconds — stagger with delay={index * 0.1}, never index * 80.",
+    "components": ["RevealFx"]
+  },
+  "RevealFx.translateY": {
+    "rule": "translateY as a number is in rem. Use translateY={1} or token \"16\" (1rem); 16 means 16rem.",
+    "components": ["RevealFx"]
+  },
+  "LogoCloud.columns": {
+    "rule": "LogoCloud extends Grid — always set columns and responsive overrides or logos stack in one column.",
+    "components": ["LogoCloud"]
+  },
+  "StatusIndicator.color": {
+    "rule": "StatusIndicator uses color=\"green\" | \"red\" | \"orange\" | \"gray\" etc. — not variant or semantic scheme names.",
+    "components": ["StatusIndicator"]
+  },
+    "rule": "Icon names must come from IconName in spec.json — never invent names like more, bell, arrowRight.",
+    "components": ["Icon", "Button", "IconButton"]
+  },
+  "Badge.duplicate": {
+    "rule": "Do not pass the same text as both title prop and children — it renders twice.",
+    "components": ["Badge"]
+  },
+  "Tag.duplicate": {
+    "rule": "Do not pass the same text as both label prop and children — it renders twice.",
+    "components": ["Tag"]
+  },
+  "color.tokens": {
+    "rule": "Colors are semantic tokens ({scheme}-{weight}), never hex/rgb. background also accepts surface | overlay | page | transparent.",
+    "components": ["Column", "Row", "Text", "Button"]
+  },
+  "color.background-weak": {
+    "rule": "*-background-weak is nearly the page color — invisible as accent. Use alpha tokens (brand-alpha-medium) for glows.",
+    "components": ["Background"]
+  },
+  "layout.shorthands": {
+    "rule": "Use fill not fillWidth fillHeight; center not horizontal=\"center\" vertical=\"center\"; Row/Column not Flex direction=.",
+    "components": ["Row", "Column", "Flex", "Grid"]
+  },
+  "layout.defaults": {
+    "rule": "Never write props equal to defaults: position=\"relative\", direction on Row/Column, variant=\"primary\" on Button.",
+    "components": ["Row", "Column", "Button"]
+  },
+  "section.gaps": {
+    "rule": "Gap between page sections: 80–160 (typical 104). Inside sections: 24–40.",
+    "components": ["Column"]
+  },
+  "heading.scale": {
+    "rule": "Hero = display-strong-l/xl; section titles = display-strong-xs/s — never heading-* for section titles.",
+    "components": ["Heading"]
+  },
+  "animation.budget": {
+    "rule": "Entry animation budget: hero + at most 1–2 key moments. Animate coherent blocks all-or-none within a sibling set.",
+    "components": ["RevealFx", "CountFx"]
+  },
+  "CountFx.trigger": {
+    "rule": "CountFx has no trigger prop — drive value from useInViewport latch instead.",
+    "components": ["CountFx"]
+  },
+  "overflow.hero": {
+    "rule": "overflow=\"hidden\" on full-bleed sections clips glows into hard bands — only use when parent has radius.",
+    "components": ["Column", "Background"]
+  }
+}

package/dist/ai/manifest.json

@@ -0,0 +1,21 @@
+{
+ "version": "1.7.12",
+ "generated": "2026-07-05",
+ "files": {
+  "spec": "spec.json",
+  "catalog": "catalog.json",
+  "rules": "rules.compact.md",
+  "rulesFull": "rules.md",
+  "recipes": "recipes.md",
+  "gotchas": "gotchas.json",
+  "tasks": "tasks/index.json",
+  "examples": "examples/",
+  "blocks": "examples/blocks/manifest.json",
+  "components": "components/"
+ },
+ "bootstrap": [
+  "rules.compact.md",
+  "catalog.json"
+ ],
+ "resolve": "tasks/index.json"
+}

package/dist/ai/recipes.md

@@ -0,0 +1,149 @@
+# Once UI — decoration recipes
+
+Curated decorative patterns that keep pages premium without going over the top.
+Use them verbatim, then adjust values. All units follow rules.md #21–24.
+
+## Budget (hard limits)
+
+- **One ambient background layer per section**, and only in sections that anchor the page (hero, highlighted card, final CTA). Plain sections stay plain — contrast is what makes the decorated ones read as premium.
+- **Continuous motion** (MatrixFx flicker, BlobFx drift) in at most **two places per page**, never adjacent.
+- **One accent family per page.** Decorations use `brand-*` (or `neutral-*`); never mix brand + accent + schemes in decoration.
+- Every decorative layer: `position="absolute" top="0" left="0" fill pointerEvents="none"`, content sibling `zIndex={1}`, parent `overflow="hidden"`.
+
+## 1. Hero glow + dots
+
+Soft brand glow from the top edge with a subtle dot texture. The workhorse ambient layer.
+
+Placement matters: the wrapper is **full-bleed** (`fillWidth`, outside any `maxWidth` column) and has **no** `overflow="hidden"` — the gradient fades out via `colorEnd: "static-transparent"`. Clipping it inside a narrow container produces a hard-edged band.
+
+```tsx
+<Column fillWidth horizontal="center" paddingY="80">
+  <Background
+    position="absolute" top="0" left="0" fill pointerEvents="none"
+    gradient={{
+      display: true,
+      colorStart: "brand-alpha-medium",
+      colorEnd: "static-transparent",
+      x: 50, y: 0,
+      width: 150, height: 80,
+      opacity: 60,
+    }}
+    dots={{ display: true, color: "neutral-alpha-weak", size: "2", opacity: 40 }}
+  />
+  <Column zIndex={1} horizontal="center" gap="24" maxWidth={48}>
+    {/* hero content */}
+  </Column>
+</Column>
+```
+
+## 2. MatrixFx hero strip (with fade-out)
+
+Animated matrix field behind a hero, faded into the page with a `page-background` gradient so it doesn't compete with content. Pair exactly like this:
+
+```tsx
+<Column fillWidth minHeight="s" center overflow="hidden">
+  <MatrixFx
+    position="absolute" top="0" left="0" fill
+    flicker size={1.5} spacing={8}
+    colors={["brand-solid-strong"]}
+    bulge={{ type: "wave", duration: 3, intensity: 20, repeat: true }}
+  />
+  <Background
+    position="absolute" top="0" left="0" fill pointerEvents="none"
+    gradient={{ display: true, colorStart: "page-background", x: 0, y: 50, width: 150, height: 300 }}
+  />
+  <Column zIndex={1} center gap="16" padding="48">
+    {/* hero content */}
+  </Column>
+</Column>
+```
+
+## 3. Highlighted card glow
+
+For the emphasized item in a set (e.g. "most popular" pricing tier). Border + top glow, nothing else:
+
+```tsx
+<Card fillWidth padding="24" radius="l" background="surface" border="brand-alpha-medium" overflow="hidden">
+  <Background
+    position="absolute" top="0" left="0" fill pointerEvents="none"
+    gradient={{
+      display: true,
+      colorStart: "brand-alpha-medium",
+      colorEnd: "static-transparent",
+      x: 50, y: 0,
+      width: 200, height: 60,
+      opacity: 50,
+    }}
+  />
+  <Column zIndex={1} gap="20" fillWidth>
+    {/* card content */}
+  </Column>
+</Card>
+```
+
+## 4. BlobFx ambient panel
+
+Self-contained drifting brand/accent blobs (already blurred and pointer-transparent). Use behind a final CTA or feature visual — counts as continuous motion:
+
+```tsx
+<Card fillWidth radius="l" border="neutral-alpha-weak" overflow="hidden" padding="48">
+  <BlobFx position="absolute" top="0" left="0" fill opacity={60} seed={2} />
+  <Column zIndex={1} center gap="24">
+    {/* CTA content */}
+  </Column>
+</Card>
+```
+
+## 5. Technical texture (lines / grid)
+
+Diagonal lines or grid texture for footers of cards, table headers, "engineering" flavored strips. No motion:
+
+```tsx
+<Background
+  position="absolute" top="0" left="0" fill pointerEvents="none"
+  lines={{ display: true, color: "neutral-alpha-weak", angle: -45, size: "4" }}
+/>
+```
+
+## 6. Section divider
+
+Between major sections when the gap alone isn't enough — a short line, optionally with an eyebrow:
+
+```tsx
+<Column fillWidth horizontal="center" gap="16">
+  <Line width="40" />
+</Column>
+```
+
+## 7. Reveal stagger (entry, not ambient)
+
+Entrance animation for **one** key set per page (rules.md #27–28), viewport-triggered and latched so it plays once, when actually seen (rules.md #29):
+
+```tsx
+const ref = useRef<HTMLDivElement>(null);
+const inViewport = useInViewport(ref);
+const [seen, setSeen] = useState(false);
+useEffect(() => {
+  if (inViewport) setSeen(true);
+}, [inViewport]);
+
+<Grid ref={ref} columns="3" gap="16" s={{ columns: 1 }}>
+  {items.map((item, index) => (
+    <RevealFx key={item.id} trigger={seen} translateY="8" delay={index * 0.1}>
+      <Card ... />
+    </RevealFx>
+  ))}
+</Grid>
+```
+
+For stats, drive `CountFx` value from the same latch: `<CountFx value={seen ? 2400 : 0} separator="," />`.
+
+## Anti-patterns
+
+- Glow with `colorStart: "brand-background-weak"` — invisible against the page; use alpha tokens.
+- `width: 500` gradients — that's 125% of the container blown past its edges; stay ≤ 200 for glows.
+- Background layers without `top="0" left="0"` inside padded parents — misaligned.
+- Decorating every section — if everything glows, nothing does.
+- Two different Fx components fighting in one viewport (MatrixFx + BlobFx side by side).
+- `overflow="hidden"` on a full-bleed section (no radius) — clips the glow into a hard-edged band.
+- Animating one item out of a sibling set (only the highlighted card) — stagger all or animate none.

package/dist/ai/rules.compact.md

@@ -0,0 +1,73 @@
+# Once UI — compact codegen rules
+
+Load with task bundle from `@once-ui-system/core/ai/tasks/{intent}.json`. For production-quality composition, read matching Pro blocks from `examples/blocks/manifest.json`. Fetch component slices on demand.
+
+## Layout
+
+| Write | Never write |
+|-------|-------------|
+| `<Column gap="16">` | `<Flex direction="column">` |
+| `<Row gap="16">` | `<Flex direction="row">` |
+| `fill` | `fillWidth fillHeight` |
+| `fit` | `fitWidth fitHeight` |
+| `center` | `horizontal="center" vertical="center"` |
+
+- `Flex` only when direction changes at breakpoints: `<Row s={{ direction: "column" }}>`
+- Page skeleton: `Column as="main" fillWidth horizontal="center"` → content `Column maxWidth="l"` → sections
+- Section gaps: `"104"` between sections, `"24"`–`"40"` inside. Never `"48"` between major sections.
+- Responsive: breakpoint props `xl l m s xs` — never media queries for layout
+
+## Surfaces
+
+Static panel recipe (pricing tiers, stats, settings sections):
+
+```tsx
+<Column background="surface" border="neutral-alpha-weak" radius="l" padding="24" gap="16">
+```
+
+- `Card` = interactive only (`href` or `onClick`). Static panels = Column + surface recipe.
+- Colors: `{scheme}-{weight}` or `{scheme}-alpha-{weight}`. Never hex/rgb.
+- `background` also: `surface | overlay | page | transparent`
+
+## Typography
+
+- Hero: `display-strong-l` or `display-strong-xl`
+- Section titles: `display-strong-xs` or `display-strong-s` — not `heading-*`
+- Eyebrow: `<Text variant="label-default-s" onBackground="brand-medium">`
+- Text on layout: `textVariant` + `onBackground` on Row/Column instead of nesting Text
+
+## Decoration
+
+Absolute layers always: `position="absolute" top="0" left="0" fill pointerEvents="none"`, content `zIndex={1}`.
+
+- Gradient `width`: quarter-percent (400 = 100%). Glows: 100–200.
+- Glow colors: `brand-alpha-medium`, not `brand-background-weak`
+- Ambient layers on full-bleed section wrapper, outside `maxWidth` column
+- Budget: one ambient layer per section; motion in hero + one CTA max
+
+## Motion
+
+- `RevealFx delay` in **seconds**: `delay={index * 0.1}`
+- `RevealFx translateY`: number = rem; prefer `"8"`–`"16"` tokens
+- Viewport-trigger with `useInViewport` + latch; `CountFx` driven by `value`, no trigger prop
+- Animate all siblings in a set or none — never one lone animated card
+
+## Components
+
+| Need | Use |
+|------|-----|
+| Image | `Media` |
+| Link | `SmartLink` / `Button href` |
+| Status dot | `StatusIndicator` |
+| Loading | `Spinner` / `Skeleton` |
+| Scroll fade | `Fade` as edge strip, not wrapper |
+| Icons | `IconName` from spec only |
+| Logos grid | `LogoCloud` with `columns` set |
+
+## Defaults — omit these
+
+`position="relative"`, `direction` on Row/Column, `variant="primary"` on Button, `size="m"` when default.
+
+## Before building
+
+If design intent unclear, ask: content style, layout width, color approach, decoration level, imagery. Default: restrained, centered `maxWidth="m"`, single brand accent, one subtle gradient, no placeholder images.