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

package/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/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 Dopler
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/ai/catalog.json

@@ -1,6 +1,6 @@
 {
- "version": "2.0.0-alpha.0",
- "generated": "2026-09-16",
+ "version": "2.0.0-alpha.1",
+ "generated": "2026-09-17",
  "components": {
   "Accordion": {
    "group": "components",

package/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/ai/examples/auth.tsx

@@ -22,11 +22,10 @@ export function AuthExample() {
   return (
     <Column as="main" fillWidth center padding="24" minHeight="100vh">
       <Grid
-        fillWidth
         maxWidth="l"
         columns="2"
         radius="xl"
-        border="neutral-alpha-weak"
+        border
         overflow="hidden"
         background="surface"
         s={{ columns: 1 }}

package/ai/examples/blocks/Dashboard1.tsx

@@ -37,7 +37,7 @@ const StatCard: React.FC<StatCardProps> = ({ title, value, change, positive = tr
   }, [positive]);
 
   return (
-    <Card minWidth={12} href={href} paddingX="20" paddingTop="20" paddingBottom="80" radius="l" fillWidth direction="column" border="neutral-alpha-weak" background="transparent">
+    <Card minWidth={12} href={href} paddingX="20" paddingTop="20" paddingBottom="80" radius="l" fillWidth direction="column" border background="transparent">
       <LineChart
         pointerEvents="none"
         position="absolute"
@@ -82,7 +82,7 @@ interface ActivityItemProps {
 }
 
 const ActivityItem: React.FC<ActivityItemProps> = ({ avatar, action, time, href, icon }) => (
-  <Row fillWidth borderBottom="neutral-alpha-weak">
+  <Row fillWidth borderBottom>
     <Card direction="column" fitHeight href={href} background="transparent" border="transparent" fillWidth>
       <Row fillWidth horizontal="between" paddingX="24" height="64" vertical="center">
         <Column fillWidth gap="8">
@@ -110,7 +110,7 @@ interface StatusItemProps {
 }
 
 const StatusItem: React.FC<StatusItemProps> = ({ name, status, icon, href = "#" }) => (
-  <Row fillWidth borderBottom="neutral-alpha-weak">
+  <Row fillWidth borderBottom>
     <Card direction="column" background="transparent" href={href} border="transparent" fillWidth>
       <Row fillWidth horizontal="between" height="64" vertical="center" paddingX="24">
         <Row vertical="center" gap="12">
@@ -240,7 +240,7 @@ export const Dashboard1: React.FC = () => {
 
                 <LineChart
                   minHeight={20}
-                  border="neutral-alpha-weak"
+                  border
                   axis="x"
                   grid="y"
                   title="Revenue growth"
@@ -277,7 +277,7 @@ export const Dashboard1: React.FC = () => {
                 />
 
                 <Grid columns="2" m={{columns: 1}} gap="m" fillWidth>
-                  <Column fillWidth border="neutral-alpha-weak" radius="l" overflow="hidden" height={20}>
+                  <Column fillWidth border radius="l" overflow="hidden" height={20}>
                     <Row vertical="center" horizontal="between" fillWidth paddingLeft="24" paddingRight="12" paddingY="12" gap="m" wrap>
                       <Heading wrap="nowrap" variant="heading-strong-s">
                         Project status
@@ -295,7 +295,7 @@ export const Dashboard1: React.FC = () => {
                       </Row>
                     </Row>
                     
-                    <Column fillWidth border="neutral-alpha-weak" topRadius="l" overflowY="auto">
+                    <Column fillWidth border topRadius="l" overflowY="auto">
                       {[
                         { name: "Mobile App Development", status: "At Risk", icon: "code" as IconName },
                         { name: "Marketing Campaign", status: "On Track", icon: "sparkle" as IconName },
@@ -314,7 +314,7 @@ export const Dashboard1: React.FC = () => {
                     </Column>
                   </Column>
 
-                  <Column border="neutral-alpha-weak" radius="l" fillWidth overflow="hidden" height={20}>
+                  <Column border radius="l" fillWidth overflow="hidden" height={20}>
                     <Row fillWidth vertical="center" horizontal="between" paddingLeft="24" paddingRight="12" paddingY="12" gap="16" wrap>
                       <Heading wrap="nowrap" variant="heading-strong-s">
                         Recent activity
@@ -323,7 +323,7 @@ export const Dashboard1: React.FC = () => {
                         View all
                       </Button>
                     </Row>
-                    <Column fillWidth border="neutral-alpha-weak" topRadius="l" overflowY="auto">
+                    <Column fillWidth border topRadius="l" overflowY="auto">
                       {[
                         {
                           avatar: "/images/creators/lorant.jpg",

package/ai/examples/blocks/Feed3.tsx

@@ -34,7 +34,7 @@ export const Feed3: React.FC<React.ComponentProps<typeof Column>> = ({ ...flex }
 
   return (
     <Column fill {...flex}>
-      <Row fillWidth paddingX="24" paddingY="8" background="surface" borderBottom="neutral-alpha-weak" vertical="center" gap="12">
+      <Row fillWidth paddingX="24" paddingY="8" background="surface" borderBottom vertical="center" gap="12">
         <Text variant="label-default-s">👋 | intro</Text>
         <Row minWidth="4" minHeight="4" background="neutral-strong" radius="full"/>
         <Text variant="body-default-xs" onBackground="neutral-weak">Let us know a bit about you!</Text>
@@ -65,7 +65,7 @@ export const Feed3: React.FC<React.ComponentProps<typeof Column>> = ({ ...flex }
                               key={aIdx}
                               maxWidth={20}
                               src={att.media}
-                              border="neutral-alpha-weak"
+                              border
                               radius="l"
                               sizes="320px"
                             />
@@ -75,9 +75,9 @@ export const Feed3: React.FC<React.ComponentProps<typeof Column>> = ({ ...flex }
                     ) : (
                       messages.attachments[0]?.media && (
                         messages.attachments[0].media.includes("youtube.com") || messages.attachments[0].media.includes("youtu.be") ? (
-                          <Media maxWidth={32} border="neutral-alpha-weak" aspectRatio="16/9" marginTop="16" src={messages.attachments[0].media} radius="l" sizes="320px"/>
+                          <Media maxWidth={32} border aspectRatio="16/9" marginTop="16" src={messages.attachments[0].media} radius="l" sizes="320px"/>
                         ) : (messages.attachments[0].media.match(/\.(png|jpg|jpeg|gif|webp)$/i)) ? (
-                          <Media maxWidth={32} border="neutral-alpha-weak" marginTop="16" src={messages.attachments[0].media} radius="l" sizes="320px"/>
+                          <Media maxWidth={32} border marginTop="16" src={messages.attachments[0].media} radius="l" sizes="320px"/>
                         ) : (
                           <Row maxWidth={24} marginTop="16">
                             <OgCard url={messages.attachments[0].media} description={false} />

package/ai/examples/blocks/Header2.tsx

@@ -29,7 +29,7 @@ export const Header2: React.FC<HeaderProps> = ({ authenticated, avatar, ...flex
       />
       <Row
         as="header"
-        border="neutral-alpha-weak"
+        border
         maxWidth="m"
         paddingX="m"
         radius="l"

package/ai/examples/blocks/Header4.tsx

@@ -39,8 +39,7 @@ export const Header4: React.FC<HeaderProps> = ({ cartCount = 0, ...flex }) => {
             <Row
               data-scaling="90"
               position="absolute"
-              vertical="center"
-              horizontal="center"
+              center
               textVariant="body-default-xs"
               solid="brand-strong"
               onSolid="brand-strong"

package/ai/examples/blocks/Productivity1.tsx

@@ -237,7 +237,7 @@ export const Productivity1 = () => {
             <Column
               key={index}
               minWidth={20}
-              border="neutral-alpha-weak"
+              border
               fillWidth
               paddingX="4"
               radius="m-4"

package/ai/examples/blocks/Roadmap1.tsx

@@ -79,7 +79,7 @@ export function Roadmap1() {
           
           <Row gap="4" fillWidth overflowX="auto" paddingBottom="16">
             {product.columns.map((column, columnIndex) => (
-              <Column key={columnIndex} padding="4" gap="4" radius="s-4" border="neutral-alpha-weak" background="overlay" fillWidth minWidth={20}>
+              <Column key={columnIndex} padding="4" gap="4" radius="s-4" border background="overlay" fillWidth minWidth={20}>
                 <Row fillWidth vertical="center" gap="8" paddingY="8" paddingX="16">
                   <Text variant="label-default-m">
                     {column.title}
@@ -99,7 +99,7 @@ export function Roadmap1() {
                     return typedTask.href ? (
                       <Card
                         onBackground="neutral-strong"
-                        border="neutral-alpha-weak"
+                        border
                         fillWidth
                         radius="s"
                         key={taskIndex} 
@@ -111,7 +111,7 @@ export function Roadmap1() {
                     ) : (
                       <Column
                         onBackground="neutral-strong"
-                        border="neutral-alpha-weak"
+                        border
                         fillWidth
                         radius="s"
                         key={taskIndex}

package/ai/examples/blocks/Sidebar1.tsx

@@ -16,7 +16,7 @@ export const Sidebar1: React.FC<React.ComponentProps<typeof Column>> = ({ ...fle
     fillHeight
     maxWidth={18}
     background="surface"
-    borderRight="neutral-alpha-weak"
+    borderRight
     padding="8"
     gap="4"
     {...flex}

package/ai/examples/blocks/Sidebar2.tsx

@@ -4,7 +4,7 @@ import { Column, Text, ToggleButton } from "@once-ui-system/core";
 
 /** Productivity sidebar — minimal stub for Productivity1 reference */
 export const Sidebar2: React.FC<React.ComponentProps<typeof Column>> = ({ ...flex }) => (
-  <Column fillHeight maxWidth={18} background="surface" borderRight="neutral-alpha-weak" padding="8" gap="4" {...flex}>
+  <Column fillHeight maxWidth={18} background="surface" borderRight padding="8" gap="4" {...flex}>
     <Text variant="label-default-s" onBackground="neutral-weak" padding="12">
       Workspace
     </Text>

package/ai/examples/blocks/Table1.tsx

@@ -94,7 +94,7 @@ export const Table1: React.FC<Table1Props> = ({
   };
 
   return (
-    <Column fillWidth radius="l" border="neutral-alpha-weak" {...flex}>
+    <Column fillWidth radius="l" border {...flex}>
       <Row fillWidth horizontal="between" paddingY="12" paddingRight="12" paddingLeft="24" gap="16" vertical="center" s={{direction: "column",}}>
         <Row fillWidth gap="12" vertical="center" horizontal="between">
           {selectable && someCurrentSelected ? (
@@ -124,8 +124,8 @@ export const Table1: React.FC<Table1Props> = ({
         )}
       </Row>
       <Column fillWidth overflowX="auto">
-        <Column fillWidth radius="l" border="neutral-alpha-weak" overflow="hidden">
-          <Row fillWidth gap="16" paddingX="24" paddingY="12" borderBottom="neutral-alpha-weak">
+        <Column fillWidth radius="l" border overflow="hidden">
+          <Row fillWidth gap="16" paddingX="24" paddingY="12" borderBottom>
             {selectable && (
               <Row textVariant="label-default-s" vertical="center" gap="16">
                 <Checkbox

package/ai/examples/dashboard.tsx

@@ -55,7 +55,7 @@ export function DashboardExample() {
 
   return (
     <Column as="main" fillWidth horizontal="center" paddingY="48" paddingX="24" gap="40">
-      <Column fillWidth maxWidth="l" gap="40">
+      <Column maxWidth="l" gap="40">
         <Row fillWidth horizontal="between" vertical="end" gap="24" s={{ direction: "column", horizontal: "start" }}>
           <Column gap="8">
             <Text variant="label-default-s" onBackground="brand-medium">
@@ -79,7 +79,7 @@ export function DashboardExample() {
         <Grid ref={statsRef} columns="4" gap="16" m={{ columns: 2 }} s={{ columns: 1 }}>
           {stats.map((stat, index) => (
             <RevealFx key={stat.label} fill revealed={seen} translateY="8" delay={index * 100}>
-              <Column background="surface" border="neutral-alpha-weak" radius="l" padding="24" gap="16">
+              <Column background="surface" border radius="l" padding="24" gap="16">
                 <Row fillWidth horizontal="between" vertical="center">
                   <Text variant="label-default-s" onBackground="neutral-weak">
                     {stat.label}
@@ -109,7 +109,7 @@ export function DashboardExample() {
         </Grid>
 
         <Grid columns="2" gap="24" s={{ columns: 1 }}>
-          <Column background="surface" border="neutral-alpha-weak" radius="l" padding="24" gap="16" minHeight={32}>
+          <Column background="surface" border radius="l" padding="24" gap="16" minHeight={32}>
             <Heading as="h2" variant="heading-strong-s">
               Revenue trend
             </Heading>
@@ -120,7 +120,7 @@ export function DashboardExample() {
               </Text>
             </Column>
           </Column>
-          <Column background="surface" border="neutral-alpha-weak" radius="l" padding="24" gap="16" minHeight={32}>
+          <Column background="surface" border radius="l" padding="24" gap="16" minHeight={32}>
             <Heading as="h2" variant="heading-strong-s">
               Signups by channel
             </Heading>
@@ -133,7 +133,7 @@ export function DashboardExample() {
           </Column>
         </Grid>
 
-        <Column background="surface" border="neutral-alpha-weak" radius="l" padding="24" gap="24">
+        <Column background="surface" border radius="l" padding="24" gap="24">
           <Row fillWidth horizontal="between" vertical="center">
             <Heading as="h2" variant="heading-strong-s">
               Recent activity

package/ai/examples/marketing-hero.tsx

@@ -103,7 +103,7 @@ export function MarketingHeroExample() {
 
       {/* Feature grid — left-aligned section header, not repeated centered blocks */}
       <Column fillWidth horizontal="center">
-        <Column fillWidth maxWidth="l" gap="40">
+        <Column maxWidth="l" gap="40">
           <Column gap="12" maxWidth={32}>
             <Text variant="label-default-s" onBackground="brand-medium">
               Components
@@ -117,7 +117,7 @@ export function MarketingHeroExample() {
               <Column
                 key={feature.title}
                 background="surface"
-                border="neutral-alpha-weak"
+                border
                 radius="l"
                 padding="24"
                 gap="16"

package/ai/examples/pricing.tsx

@@ -95,7 +95,7 @@ export function PricingExample() {
       </Column>
 
       <Column fillWidth horizontal="center">
-        <Column fillWidth maxWidth="l" gap="40">
+        <Column maxWidth="l" gap="40">
           <Row fillWidth horizontal="between" vertical="end" gap="24" s={{ direction: "column", horizontal: "start" }}>
             <Heading as="h2" variant="display-strong-xs">
               Three plans, one decision
@@ -181,7 +181,7 @@ export function PricingExample() {
       </Column>
 
       <Column fillWidth horizontal="center" background="neutral-alpha-weak" paddingY="80" paddingX="24">
-        <Column fillWidth maxWidth="l" gap="40">
+        <Column maxWidth="l" gap="40">
           <Heading as="h2" variant="display-strong-xs">
             Every feature, side by side
           </Heading>
@@ -203,7 +203,7 @@ export function PricingExample() {
       </Column>
 
       <Column fillWidth horizontal="center">
-        <Column fillWidth maxWidth="l" radius="xl" border="neutral-alpha-weak" overflow="hidden" padding="64" center>
+        <Column maxWidth="l" radius="xl" border overflow="hidden" padding="64" center>
           <BlobFx position="absolute" top="0" left="0" fill opacity={60} seed={2} />
           <Column zIndex={1} center gap="24" maxWidth={40}>
             <Heading as="h2" variant="display-strong-s" align="center">

package/ai/examples/settings.tsx

@@ -29,7 +29,7 @@ const sections = [
 export function SettingsExample() {
   return (
     <Column as="main" fillWidth horizontal="center" paddingY="48" paddingX="24">
-      <Column fillWidth maxWidth="l" gap="40">
+      <Column maxWidth="l" gap="40">
         <Column gap="12">
           <Text variant="label-default-s" onBackground="brand-medium">
             Settings
@@ -46,7 +46,7 @@ export function SettingsExample() {
               gap="4"
               padding="16"
               background="surface"
-              border="neutral-alpha-weak"
+              border
               radius="l"
               s={{ hide: true }}
             >
@@ -66,7 +66,7 @@ export function SettingsExample() {
           }
           rightPanel={
             <Column flex={1} gap="24">
-            <Column background="surface" border="neutral-alpha-weak" radius="l" padding="24" gap="24">
+            <Column background="surface" border radius="l" padding="24" gap="24">
               <Heading as="h2" variant="heading-strong-m">
                 Profile
               </Heading>
@@ -97,7 +97,7 @@ export function SettingsExample() {
               </Row>
             </Column>
 
-            <Column background="surface" border="neutral-alpha-weak" radius="l" padding="24" gap="24">
+            <Column background="surface" border radius="l" padding="24" gap="24">
               <Heading as="h2" variant="heading-strong-m">
                 Notifications
               </Heading>

package/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"
     ]
@@ -101,13 +101,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/ai/manifest.json

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

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
@@ -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.1",
+ "generated": "2026-09-17",
  "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\"",

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.1",
+ "generated": "2026-09-17",
  "components": {
   "Accordion": {
    "group": "components",

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