@once-ui-system/core 2.0.0-alpha.0 → 2.0.0-alpha.2

package/ai/recipes.md

@@ -87,7 +87,7 @@ For the emphasized item in a set (e.g. "most popular" pricing tier). Border + to
 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">
+<Card fillWidth radius="l" border overflow="hidden" padding="48">
   <BlobFx position="absolute" top="0" left="0" fill opacity={60} seed={2} />
   <Column zIndex={1} center gap="24">
     {/* CTA content */}

package/ai/rules.compact.md

@@ -11,6 +11,9 @@ Load with task bundle from `@once-ui-system/core/ai/tasks/{intent}.json`. For an
 | `fill` | `fillWidth fillHeight` |
 | `fit` | `fitWidth fitHeight` |
 | `center` | `horizontal="center" vertical="center"` |
+| `maxWidth="l"` | `fillWidth maxWidth="l"` |
+| `fillWidth` | `fillWidth minWidth={0}` |
+| `border` | `border="neutral-alpha-weak"` |
 
 - `Flex` only when direction changes at breakpoints: `<Row s={{ direction: "column" }}>`
 - Page skeleton: `Column as="main" fillWidth horizontal="center"` → content `Column maxWidth="l"` → sections
@@ -22,9 +25,10 @@ Load with task bundle from `@once-ui-system/core/ai/tasks/{intent}.json`. For an
 Static panel recipe (pricing tiers, stats, settings sections):
 
 ```tsx
-<Column background="surface" border="neutral-alpha-weak" radius="l" padding="24" gap="16">
+<Column background="surface" border radius="l" padding="24" gap="16">
 ```
 
+- Bare `border` (and `borderTop`, `borderBottom`, …) = the default border. Name a colour only to deviate: `border="brand-alpha-medium"`.
 - `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`
@@ -40,6 +44,8 @@ Static panel recipe (pricing tiers, stats, settings sections):
 
 Absolute layers always: `position="absolute" top="0" left="0" fill pointerEvents="none"`, content `zIndex={1}`.
 
+- `zIndex` only inside that layer group (or on a sticky header over its pane). Never on a lone element, never a page-wide ladder.
+
 - 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
@@ -81,7 +87,7 @@ from `spec.json`.
 
 ## Defaults — omit these
 
-`position="relative"`, `direction` on Row/Column, `variant="primary"` on Button, `size="m"` when default.
+`position="relative"`, `direction` on Row/Column, `variant="primary"` on Button, `size="m"` when default, `fillWidth` beside `maxWidth`, `minWidth={0}` beside `fillWidth`, a border colour that restates the default.
 
 ## Before building
 

package/ai/rules.md

@@ -40,10 +40,22 @@ If you can't ask (or the user says "you decide"), default to: restrained, center
 <Row fillWidth fillHeight horizontal="center" vertical="center">...</Row>
 ```
 
-3. Never write a prop that equals its default. The spec marks defaults with `= value`. Common offenders:
+3. Never write a prop that equals its default, or one that another prop on the same element already implies. The spec marks defaults with `= value`. Common offenders:
    - `position="relative"` (default on all layout components)
    - `direction="row"` on `Row`, `direction="column"` on `Column`
    - `variant="primary"`, `size="m"` on `Button`
+   - `fillWidth` beside `maxWidth` — `maxWidth` already fills the width up to the cap
+   - `minWidth={0}` beside `fillWidth` — `fillWidth` already sets `min-width: 0`
+   - a colour on `border` (or `borderTop`, `borderBottom`, `borderX`, …) that only restates the default — bare `border` draws the default border; name a colour only to deviate from it
+
+```tsx
+// Good
+<Column maxWidth="l" border radius="l">
+// Bad
+<Column fillWidth maxWidth="l" minWidth={0} position="relative" border="neutral-alpha-weak" radius="l">
+```
+
+3b. `zIndex` belongs to a stacking group, not to a page. Use it only inside an isolated group that needs an order — a decorative absolute layer and the content sibling above it (rule 21), a sticky header over the pane it covers — and keep the values small within that group. A `zIndex` on a lone element, or a page-wide ladder of `zIndex={3}`, `{5}`, `{9}`, means the hierarchy is being managed by hand; restructure the tree instead.
 
 ## Spacing and sizing
 
@@ -66,10 +78,10 @@ If you can't ask (or the user says "you decide"), default to: restrained, center
    - `background` also accepts `surface | overlay | page | transparent`
    - `onBackground` colors text/icons on a background
 
-8. Standard surface recipe: `background="surface"` (or `"overlay"` over imagery) + `border="neutral-alpha-weak"` (or `-medium`) + `radius="l"`.
+8. Standard surface recipe: `background="surface"` (or `"overlay"` over imagery) + `border` + `radius="l"`. Bare `border` is the default border; name a colour (`border="neutral-alpha-medium"`, `border="brand-alpha-medium"`) only when the surface should differ from it.
 
 ```tsx
-<Column background="surface" border="neutral-alpha-weak" radius="l" padding="24" gap="16">
+<Column background="surface" border radius="l" padding="24" gap="16">
 ```
 
 ## Text
@@ -105,7 +117,7 @@ If you can't ask (or the user says "you decide"), default to: restrained, center
 
 13. Use the distinctive features when the design calls for them — they exist and are cheap:
     - `Dialog` supports `stack` (stacked dialogs) and `base` props
-    - Effects: `RevealFx`, `LetterFx`, `TypeFx`, `CountFx`, `GlitchFx`, `HoloFx`, `TiltFx`, `FlipFx`, `MatrixFx`, `BlobFx`, `Particle`, `ShineFx`, `CelebrationFx`
+    - Effects: `RevealFx`, `LetterFx`, `TypeFx`, `CountFx`, `GlitchFx`, `HoloFx`, `TiltFx`, `FlipFx`, `MatrixFx`, `BlobFx`, `ParticleFx`, `ShineFx`, `CelebrationFx`
     - `CursorCard`, `HoverCard`, `ContextMenu`, `EmojiPicker`, `CompareImage`, `OgCard`, `Timeline`, `MasonryGrid`, `InfiniteScroll`, `SegmentedControl`, `Kbar` (command palette)
     - Forms: `Input`, `PasswordInput`, `OTPInput`, `NumberInput`, `TagInput`, `Select`, `DatePicker`, `DateRangePicker`, `ColorInput`, `Slider`, `Switch`, `Checkbox`, `Chip`
 
@@ -183,7 +195,7 @@ the card it was meant to support.
     <Grid columns={5} s={{ columns: 3 }} gap="8" fillWidth>
       {items.map(i => (
         <Column key={i} aspectRatio="1 / 1" padding="12" radius="l"
-                background="page" border="neutral-alpha-weak" vertical="between">
+                background="page" border vertical="between">
           {/* a preview of the thing, not just its name */}
         </Column>
       ))}
@@ -204,7 +216,7 @@ in that order.
 <Background position="absolute" top="0" left="0" fill pointerEvents="none" ... />
 ```
 
-Siblings holding content get `zIndex={1}`. `overflow="hidden"` goes on the parent **only when it has a radius** (cards, panels) — clipping a full-bleed section turns the glow into a hard-edged band.
+Siblings holding content get `zIndex={1}`. That layer and its content sibling are the whole stacking group — nothing else in the section needs a `zIndex` (rule 3b). `overflow="hidden"` goes on the parent **only when it has a radius** (cards, panels) — clipping a full-bleed section turns the glow into a hard-edged band.
 
 21b. Ambient section layers (hero glows) live on the **full-width section wrapper**, outside the `maxWidth` content column, with generous room (`paddingY="80"`+). Inside a narrow container the gradient gets clipped at the container edge and reads as a misplaced card:
 

package/ai/spec.json

@@ -1,7 +1,7 @@
 {
  "name": "@once-ui-system/core",
- "version": "2.0.0-alpha.0",
- "generated": "2026-09-16",
+ "version": "2.0.0-alpha.2",
+ "generated": "2026-09-23",
  "format": "props are 'type', 'type = default', or '!type' (required). Components with 'mixins' also accept all props of those mixins. 'extends' means all props of that component are accepted. In 'types', an array lists a union's allowed values, an object gives a shape's fields in the same notation as props, and a string is the type as written — usually pointing at a component whose props are already listed.",
  "tokens": {
   "StaticSpacingToken": "\"0\" | \"1\" | \"2\" | \"4\" | \"8\" | \"12\" | \"16\" | \"20\" | \"24\" | \"32\" | \"40\" | \"48\" | \"56\" | \"64\" | \"72\" | \"80\" | \"104\" | \"128\" | \"160\"",
@@ -1180,6 +1180,7 @@
    "props": {
     "variant": "\"info\" | \"danger\" | \"warning\" | \"success\" = info",
     "showIcon": "boolean = true",
+    "icon": "IconName",
     "title": "string",
     "description": "string",
     "showCloseButton": "boolean = false",
@@ -1233,6 +1234,19 @@
     "style": "React.CSSProperties"
    }
   },
+  "Form": {
+   "group": "components",
+   "props": {
+    "density": "\"stacked\" | \"tight\" | \"spacious\" = tight",
+    "columns": "FormColumns",
+    "size": "TShirtSizes",
+    "as": "\"div\" | \"form\" = div",
+    "onSubmit": "React.FormEventHandler<HTMLFormElement>",
+    "className": "string",
+    "style": "React.CSSProperties",
+    "children": "React.ReactNode"
+   }
+  },
   "GlitchFx": {
    "group": "components",
    "extends": [
@@ -1436,7 +1450,7 @@
     "id": "!string",
     "label": "string",
     "placeholder": "string",
-    "size": "TShirtSizes = m",
+    "size": "TShirtSizes",
     "error": "boolean = false",
     "errorMessage": "ReactNode",
     "description": "ReactNode",
@@ -1450,7 +1464,8 @@
     "characterCount": "boolean",
     "cursor": "undefined | \"interactive\"",
     "validate": "(value: ReactNode) => ReactNode | null",
-    "loading": "boolean = false"
+    "loading": "boolean = false",
+    "span": "number"
    }
   },
   "InteractiveDetails": {
@@ -1782,7 +1797,7 @@
     "autoFocus": "boolean = false"
    }
   },
-  "Particle": {
+  "ParticleFx": {
    "group": "components",
    "extends": [
     "Flex"
@@ -1960,7 +1975,15 @@
    ],
    "props": {
     "items": "!React.ReactNode[]",
-    "controlPlacement": "\"top-start\" | \"top-center\" | \"top-end\" | \"top-between\" | \"bottom-start\" | \"bottom-center\" | \"bottom-end\" | \"bottom-between\" = top-start"
+    "controlPlacement": "ScrollContainerControlPlacement = top-start",
+    "infinite": "boolean = false",
+    "markers": "boolean | \"top\" | \"bottom\" = false",
+    "draggable": "boolean = true",
+    "step": "number = 1",
+    "clip": "boolean = false",
+    "proximity": "boolean | number = false",
+    "active": "number",
+    "onActiveChange": "(index: number) => void"
    }
   },
   "ScrollToTop": {
@@ -2295,7 +2318,7 @@
     "label": "string",
     "placeholder": "string",
     "lines": "number | \"auto\" = auto",
-    "size": "TShirtSizes = m",
+    "size": "TShirtSizes",
     "error": "boolean = false",
     "errorMessage": "ReactNode",
     "description": "ReactNode",
@@ -2308,7 +2331,8 @@
     "characterCount": "boolean",
     "resize": "\"horizontal\" | \"vertical\" | \"both\" | \"none\" = vertical",
     "validate": "(value: ReactNode) => ReactNode | null",
-    "disabled": "boolean = false"
+    "disabled": "boolean = false",
+    "span": "number"
    }
   },
   "TiltFx": {
@@ -2445,7 +2469,8 @@
     "StyleProps"
    ],
    "props": {
-    "collapsed": "boolean"
+    "collapsed": "boolean",
+    "direction": "\"row\" | \"column\" = row"
    }
   },
   "User": {
@@ -2521,7 +2546,7 @@
     "blob": "Omit<React.ComponentProps<typeof BlobFx>, \"children\">",
     "matrix": "Omit<React.ComponentProps<typeof MatrixFx>, \"children\">",
     "weather": "Omit<React.ComponentProps<typeof WeatherFx>, \"children\">",
-    "particle": "Omit<React.ComponentProps<typeof Particle>, \"children\">",
+    "particle": "Omit<React.ComponentProps<typeof ParticleFx>, \"children\">",
     "celebration": "Omit<React.ComponentProps<typeof CelebrationFx>, \"children\">",
     "children": "React.ReactNode"
    }

package/ai/tasks/settings.json

@@ -28,7 +28,7 @@
     "layout.defaults"
   ],
   "quality": {
-    "surfaceRecipe": "background=\"surface\" border=\"neutral-alpha-weak\" radius=\"l\" padding=\"24\"",
+    "surfaceRecipe": "background=\"surface\" border radius=\"l\" padding=\"24\"",
     "dangerZone": "border=\"danger-alpha-medium\" on danger actions only"
   }
 }

package/dist/AGENTS.md

@@ -47,7 +47,7 @@ If you cannot read `node_modules`, use the docs host (may not match your install
 
 - Use `Column` / `Row`, not `Flex` unless direction changes at breakpoints
 - Use `fill`, not `fillWidth fillHeight`; use `center`, not `horizontal="center" vertical="center"`
-- Static panels: `Column background="surface" border="neutral-alpha-weak" radius="l" padding="24"`
+- Static panels: `Column background="surface" border radius="l" padding="24"`
 - `Card` is interactive only (`href` or `onClick`)
 
 Full rules: `@once-ui-system/core/ai/rules.compact.md`

package/dist/ai/catalog.json

@@ -1,6 +1,6 @@
 {
- "version": "2.0.0-alpha.0",
- "generated": "2026-09-16",
+ "version": "2.0.0-alpha.2",
+ "generated": "2026-09-23",
  "components": {
   "Accordion": {
    "group": "components",
@@ -430,6 +430,13 @@
     "components"
    ]
   },
+  "Form": {
+   "group": "components",
+   "purpose": "Form component",
+   "tags": [
+    "components"
+   ]
+  },
   "GlitchFx": {
    "group": "components",
    "extends": [
@@ -683,12 +690,12 @@
     "components"
    ]
   },
-  "Particle": {
+  "ParticleFx": {
    "group": "components",
    "extends": [
     "Flex"
    ],
-   "purpose": "Particle component",
+   "purpose": "ParticleFx component",
    "tags": [
     "components"
    ]

package/dist/ai/components/Effect.json

@@ -20,7 +20,7 @@
   "blob": "Omit<React.ComponentProps<typeof BlobFx>, \"children\">",
   "matrix": "Omit<React.ComponentProps<typeof MatrixFx>, \"children\">",
   "weather": "Omit<React.ComponentProps<typeof WeatherFx>, \"children\">",
-  "particle": "Omit<React.ComponentProps<typeof Particle>, \"children\">",
+  "particle": "Omit<React.ComponentProps<typeof ParticleFx>, \"children\">",
   "celebration": "Omit<React.ComponentProps<typeof CelebrationFx>, \"children\">",
   "children": "React.ReactNode"
  },

package/dist/ai/components/Feedback.json

@@ -15,6 +15,7 @@
  "props": {
   "variant": "\"info\" | \"danger\" | \"warning\" | \"success\" = info",
   "showIcon": "boolean = true",
+  "icon": "IconName",
   "title": "string",
   "description": "string",
   "showCloseButton": "boolean = false",

package/dist/ai/components/Form.json

@@ -0,0 +1,15 @@
+{
+ "name": "Form",
+ "group": "components",
+ "props": {
+  "density": "\"stacked\" | \"tight\" | \"spacious\" = tight",
+  "columns": "FormColumns",
+  "size": "TShirtSizes",
+  "as": "\"div\" | \"form\" = div",
+  "onSubmit": "React.FormEventHandler<HTMLFormElement>",
+  "className": "string",
+  "style": "React.CSSProperties",
+  "children": "React.ReactNode"
+ },
+ "mixinsRef": []
+}

package/dist/ai/components/Input.json

@@ -5,7 +5,7 @@
   "id": "!string",
   "label": "string",
   "placeholder": "string",
-  "size": "TShirtSizes = m",
+  "size": "TShirtSizes",
   "error": "boolean = false",
   "errorMessage": "ReactNode",
   "description": "ReactNode",
@@ -19,7 +19,8 @@
   "characterCount": "boolean",
   "cursor": "undefined | \"interactive\"",
   "validate": "(value: ReactNode) => ReactNode | null",
-  "loading": "boolean = false"
+  "loading": "boolean = false",
+  "span": "number"
  },
  "mixinsRef": []
 }

package/dist/ai/components/{Particle.json → ParticleFx.json}

@@ -1,5 +1,5 @@
 {
- "name": "Particle",
+ "name": "ParticleFx",
  "group": "components",
  "extends": [
   "Flex"

package/dist/ai/components/ScrollContainer.json

@@ -15,7 +15,15 @@
  ],
  "props": {
   "items": "!React.ReactNode[]",
-  "controlPlacement": "\"top-start\" | \"top-center\" | \"top-end\" | \"top-between\" | \"bottom-start\" | \"bottom-center\" | \"bottom-end\" | \"bottom-between\" = top-start"
+  "controlPlacement": "ScrollContainerControlPlacement = top-start",
+  "infinite": "boolean = false",
+  "markers": "boolean | \"top\" | \"bottom\" = false",
+  "draggable": "boolean = true",
+  "step": "number = 1",
+  "clip": "boolean = false",
+  "proximity": "boolean | number = false",
+  "active": "number",
+  "onActiveChange": "(index: number) => void"
  },
  "mixinsRef": [
   "CommonProps",

package/dist/ai/components/Textarea.json

@@ -6,7 +6,7 @@
   "label": "string",
   "placeholder": "string",
   "lines": "number | \"auto\" = auto",
-  "size": "TShirtSizes = m",
+  "size": "TShirtSizes",
   "error": "boolean = false",
   "errorMessage": "ReactNode",
   "description": "ReactNode",
@@ -19,7 +19,8 @@
   "characterCount": "boolean",
   "resize": "\"horizontal\" | \"vertical\" | \"both\" | \"none\" = vertical",
   "validate": "(value: ReactNode) => ReactNode | null",
-  "disabled": "boolean = false"
+  "disabled": "boolean = false",
+  "span": "number"
  },
  "mixinsRef": []
 }

package/dist/ai/components/ThemeSwitcher.json

@@ -14,7 +14,8 @@
   "StyleProps"
  ],
  "props": {
-  "collapsed": "boolean"
+  "collapsed": "boolean",
+  "direction": "\"row\" | \"column\" = row"
  },
  "mixinsRef": [
   "CommonProps",

package/dist/ai/eval-tasks.md

@@ -25,7 +25,8 @@ is found in the wild.
 Mechanical (count occurrences):
 
 - [ ] Compiles / no invented props or components
-- [ ] Redundant-default props (`position="relative"`, `variant="primary"` on Button, ...) — target: 0
+- [ ] Redundant-default props (`position="relative"`, `variant="primary"` on Button, `fillWidth` beside `maxWidth`, `minWidth={0}` beside `fillWidth`, `border="neutral-alpha-weak"` for the default border, ...) — target: 0
+- [ ] `zIndex` outside an isolated stacking group (nothing absolute/fixed/sticky nearby) — 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

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

@@ -69,9 +69,9 @@
     {
       "id": "Footer4",
       "file": "Footer4.tsx",
-      "title": "Premium footer with TypeFx + Particle",
+      "title": "Premium footer with TypeFx + ParticleFx",
       "tags": ["footer", "marketing", "effect"],
-      "components": ["Background", "Particle", "TypeFx", "Mask", "Avatar", "Tag"],
+      "components": ["Background", "ParticleFx", "TypeFx", "Mask", "Avatar", "Tag"],
       "patterns": ["animated wordmark", "particle decoration", "masked gradient"],
       "tasks": ["marketing-hero"],
       "standalone": true

package/dist/ai/gotchas.json

@@ -20,7 +20,7 @@
     ]
   },
   "Card.interactive": {
-    "rule": "Card is for interactive surfaces only (href or onClick). Static panels use Column + background=\"surface\" border=\"neutral-alpha-weak\" radius=\"l\".",
+    "rule": "Card is for interactive surfaces only (href or onClick). Static panels use Column + background=\"surface\" border radius=\"l\".",
     "components": [
       "Card"
     ]
@@ -76,6 +76,13 @@
       "Tag"
     ]
   },
+  "Timeline.notScrubber": {
+    "rule": "Timeline lays a sequence of steps down the page. For a video or audio editor's timeline — a playhead over stacked tracks of movable, trimmable blocks — use Scrubber. Do not build one out of Flex and absolute positioning.",
+    "components": [
+      "Timeline",
+      "Scrubber"
+    ]
+  },
   "color.tokens": {
     "rule": "Colors are semantic tokens ({scheme}-{weight}), never hex/rgb. background also accepts surface | overlay | page | transparent.",
     "components": [
@@ -101,13 +108,30 @@
     ]
   },
   "layout.defaults": {
-    "rule": "Never write props equal to defaults: position=\"relative\", direction on Row/Column, variant=\"primary\" on Button.",
+    "rule": "Never write props equal to defaults or implied by another prop on the element: position=\"relative\", direction on Row/Column, variant=\"primary\" on Button, fillWidth beside maxWidth (maxWidth already fills the width), minWidth={0} beside fillWidth (fillWidth already sets min-width: 0).",
     "components": [
       "Row",
       "Column",
+      "Grid",
       "Button"
     ]
   },
+  "border.default": {
+    "rule": "Bare border (and borderTop, borderBottom, borderX, …) draws the default border. Do not write border=\"neutral-alpha-weak\" to get it; name a colour only to deviate, e.g. border=\"brand-alpha-medium\".",
+    "components": [
+      "Row",
+      "Column",
+      "Card"
+    ]
+  },
+  "zIndex.scope": {
+    "rule": "zIndex is for an isolated stacking group: an absolute decorative layer and its content sibling (zIndex={1}), or a sticky header over its pane. Never on a lone element, never a page-wide ladder of 3 / 5 / 9 — restructure the tree instead.",
+    "components": [
+      "Row",
+      "Column",
+      "Background"
+    ]
+  },
   "section.gaps": {
     "rule": "Gap between page sections: 80–160 (typical 104). Inside sections: 24–40.",
     "components": [

package/dist/ai/manifest.json

@@ -1,6 +1,6 @@
 {
- "version": "2.0.0-alpha.0",
- "generated": "2026-09-16",
+ "version": "2.0.0-alpha.2",
+ "generated": "2026-09-23",
  "files": {
   "spec": "spec.json",
   "catalog": "catalog.json",

package/dist/ai/recipes.md

@@ -87,7 +87,7 @@ For the emphasized item in a set (e.g. "most popular" pricing tier). Border + to
 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">
+<Card fillWidth radius="l" border overflow="hidden" padding="48">
   <BlobFx position="absolute" top="0" left="0" fill opacity={60} seed={2} />
   <Column zIndex={1} center gap="24">
     {/* CTA content */}

package/dist/ai/rules.compact.md

@@ -11,6 +11,9 @@ Load with task bundle from `@once-ui-system/core/ai/tasks/{intent}.json`. For an
 | `fill` | `fillWidth fillHeight` |
 | `fit` | `fitWidth fitHeight` |
 | `center` | `horizontal="center" vertical="center"` |
+| `maxWidth="l"` | `fillWidth maxWidth="l"` |
+| `fillWidth` | `fillWidth minWidth={0}` |
+| `border` | `border="neutral-alpha-weak"` |
 
 - `Flex` only when direction changes at breakpoints: `<Row s={{ direction: "column" }}>`
 - Page skeleton: `Column as="main" fillWidth horizontal="center"` → content `Column maxWidth="l"` → sections
@@ -22,9 +25,10 @@ Load with task bundle from `@once-ui-system/core/ai/tasks/{intent}.json`. For an
 Static panel recipe (pricing tiers, stats, settings sections):
 
 ```tsx
-<Column background="surface" border="neutral-alpha-weak" radius="l" padding="24" gap="16">
+<Column background="surface" border radius="l" padding="24" gap="16">
 ```
 
+- Bare `border` (and `borderTop`, `borderBottom`, …) = the default border. Name a colour only to deviate: `border="brand-alpha-medium"`.
 - `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`
@@ -40,6 +44,8 @@ Static panel recipe (pricing tiers, stats, settings sections):
 
 Absolute layers always: `position="absolute" top="0" left="0" fill pointerEvents="none"`, content `zIndex={1}`.
 
+- `zIndex` only inside that layer group (or on a sticky header over its pane). Never on a lone element, never a page-wide ladder.
+
 - 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
@@ -81,7 +87,7 @@ from `spec.json`.
 
 ## Defaults — omit these
 
-`position="relative"`, `direction` on Row/Column, `variant="primary"` on Button, `size="m"` when default.
+`position="relative"`, `direction` on Row/Column, `variant="primary"` on Button, `size="m"` when default, `fillWidth` beside `maxWidth`, `minWidth={0}` beside `fillWidth`, a border colour that restates the default.
 
 ## Before building
 

package/dist/ai/rules.md

@@ -40,10 +40,22 @@ If you can't ask (or the user says "you decide"), default to: restrained, center
 <Row fillWidth fillHeight horizontal="center" vertical="center">...</Row>
 ```
 
-3. Never write a prop that equals its default. The spec marks defaults with `= value`. Common offenders:
+3. Never write a prop that equals its default, or one that another prop on the same element already implies. The spec marks defaults with `= value`. Common offenders:
    - `position="relative"` (default on all layout components)
    - `direction="row"` on `Row`, `direction="column"` on `Column`
    - `variant="primary"`, `size="m"` on `Button`
+   - `fillWidth` beside `maxWidth` — `maxWidth` already fills the width up to the cap
+   - `minWidth={0}` beside `fillWidth` — `fillWidth` already sets `min-width: 0`
+   - a colour on `border` (or `borderTop`, `borderBottom`, `borderX`, …) that only restates the default — bare `border` draws the default border; name a colour only to deviate from it
+
+```tsx
+// Good
+<Column maxWidth="l" border radius="l">
+// Bad
+<Column fillWidth maxWidth="l" minWidth={0} position="relative" border="neutral-alpha-weak" radius="l">
+```
+
+3b. `zIndex` belongs to a stacking group, not to a page. Use it only inside an isolated group that needs an order — a decorative absolute layer and the content sibling above it (rule 21), a sticky header over the pane it covers — and keep the values small within that group. A `zIndex` on a lone element, or a page-wide ladder of `zIndex={3}`, `{5}`, `{9}`, means the hierarchy is being managed by hand; restructure the tree instead.
 
 ## Spacing and sizing
 
@@ -66,10 +78,10 @@ If you can't ask (or the user says "you decide"), default to: restrained, center
    - `background` also accepts `surface | overlay | page | transparent`
    - `onBackground` colors text/icons on a background
 
-8. Standard surface recipe: `background="surface"` (or `"overlay"` over imagery) + `border="neutral-alpha-weak"` (or `-medium`) + `radius="l"`.
+8. Standard surface recipe: `background="surface"` (or `"overlay"` over imagery) + `border` + `radius="l"`. Bare `border` is the default border; name a colour (`border="neutral-alpha-medium"`, `border="brand-alpha-medium"`) only when the surface should differ from it.
 
 ```tsx
-<Column background="surface" border="neutral-alpha-weak" radius="l" padding="24" gap="16">
+<Column background="surface" border radius="l" padding="24" gap="16">
 ```
 
 ## Text
@@ -105,7 +117,7 @@ If you can't ask (or the user says "you decide"), default to: restrained, center
 
 13. Use the distinctive features when the design calls for them — they exist and are cheap:
     - `Dialog` supports `stack` (stacked dialogs) and `base` props
-    - Effects: `RevealFx`, `LetterFx`, `TypeFx`, `CountFx`, `GlitchFx`, `HoloFx`, `TiltFx`, `FlipFx`, `MatrixFx`, `BlobFx`, `Particle`, `ShineFx`, `CelebrationFx`
+    - Effects: `RevealFx`, `LetterFx`, `TypeFx`, `CountFx`, `GlitchFx`, `HoloFx`, `TiltFx`, `FlipFx`, `MatrixFx`, `BlobFx`, `ParticleFx`, `ShineFx`, `CelebrationFx`
     - `CursorCard`, `HoverCard`, `ContextMenu`, `EmojiPicker`, `CompareImage`, `OgCard`, `Timeline`, `MasonryGrid`, `InfiniteScroll`, `SegmentedControl`, `Kbar` (command palette)
     - Forms: `Input`, `PasswordInput`, `OTPInput`, `NumberInput`, `TagInput`, `Select`, `DatePicker`, `DateRangePicker`, `ColorInput`, `Slider`, `Switch`, `Checkbox`, `Chip`
 
@@ -183,7 +195,7 @@ the card it was meant to support.
     <Grid columns={5} s={{ columns: 3 }} gap="8" fillWidth>
       {items.map(i => (
         <Column key={i} aspectRatio="1 / 1" padding="12" radius="l"
-                background="page" border="neutral-alpha-weak" vertical="between">
+                background="page" border vertical="between">
           {/* a preview of the thing, not just its name */}
         </Column>
       ))}
@@ -204,7 +216,7 @@ in that order.
 <Background position="absolute" top="0" left="0" fill pointerEvents="none" ... />
 ```
 
-Siblings holding content get `zIndex={1}`. `overflow="hidden"` goes on the parent **only when it has a radius** (cards, panels) — clipping a full-bleed section turns the glow into a hard-edged band.
+Siblings holding content get `zIndex={1}`. That layer and its content sibling are the whole stacking group — nothing else in the section needs a `zIndex` (rule 3b). `overflow="hidden"` goes on the parent **only when it has a radius** (cards, panels) — clipping a full-bleed section turns the glow into a hard-edged band.
 
 21b. Ambient section layers (hero glows) live on the **full-width section wrapper**, outside the `maxWidth` content column, with generous room (`paddingY="80"`+). Inside a narrow container the gradient gets clipped at the container edge and reads as a misplaced card: