Common gotchas

Codegen mistakes from gotchas.json — layout, surfaces, motion, and component traps.

Updated 19d ago

Key	Rule
`layout.shorthands`	Use `fill` not `fillWidth fillHeight`; `center` not `horizontal="center" vertical="center"`; `Row`/`Column` not `Flex direction=`
`layout.defaults`	Never write props equal to defaults: `position="relative"`, `direction` on Row/Column, `variant="primary"` on Button
`section.gaps`	Gap between page sections: 80–160 (typical 104). Inside sections: 24–40. Never 48 between major sections

Key

Rule

`layout.shorthands`

Use `fill` not `fillWidth fillHeight`; `center` not `horizontal="center" vertical="center"`; `Row`/`Column` not `Flex direction=`

`layout.defaults`

Never write props equal to defaults: `position="relative"`, `direction` on Row/Column, `variant="primary"` on Button

`section.gaps`

Gap between page sections: 80–160 (typical 104). Inside sections: 24–40. Never 48 between major sections

Key	Rule
`Card.interactive`	`Card` is for interactive surfaces only (`href` or `onClick`). Static panels use the Column surface recipe
`color.tokens`	Colors are semantic tokens (`{scheme}-{weight}`), never hex/rgb
`color.background-weak`	`*-background-weak` is nearly the page color — use alpha tokens (`brand-alpha-medium`) for glows

Key

Rule

`Card.interactive`

`Card` is for interactive surfaces only (`href` or `onClick`). Static panels use the Column surface recipe

`color.tokens`

Colors are semantic tokens (`{scheme}-{weight}`), never hex/rgb

`color.background-weak`

`*-background-weak` is nearly the page color — use alpha tokens (`brand-alpha-medium`) for glows

Key	Rule
`Background.absolute`	Every absolute decorative layer needs `top="0" left="0"` or it offsets by parent padding
`Background.gradient.width`	Quarter-percent units: 400 = 100%. Soft glows use width 100–200, not 500
`overflow.hero`	`overflow="hidden"` on full-bleed sections clips glows into hard bands

Key

Rule

`Background.absolute`

Every absolute decorative layer needs `top="0" left="0"` or it offsets by parent padding

`Background.gradient.width`

Quarter-percent units: 400 = 100%. Soft glows use width 100–200, not 500

`overflow.hero`

`overflow="hidden"` on full-bleed sections clips glows into hard bands

Key	Rule
`RevealFx.delay`	Delay is in seconds — stagger with `delay={index * 0.1}`, never `index * 80`
`RevealFx.translateY`	Number = rem. Use `translateY={1}` or token `"16"`; bare `16` means 16rem
`CountFx.trigger`	No `trigger` prop — drive `value` from a `useInViewport` latch
`animation.budget`	Entry animation budget: hero + at most 1–2 key moments per page

Key

Rule

`RevealFx.delay`

Delay is in **seconds** — stagger with `delay={index * 0.1}`, never `index * 80`

`RevealFx.translateY`

Number = rem. Use `translateY={1}` or token `"16"`; bare `16` means 16rem

`CountFx.trigger`

No `trigger` prop — drive `value` from a `useInViewport` latch

`animation.budget`

Entry animation budget: hero + at most 1–2 key moments per page

Key	Rule
`Icon.names`	Icon names must come from `IconName` in spec.json — never invent
`Badge.duplicate`	Don't pass the same text as both `title` prop and children
`Tag.duplicate`	Don't pass the same text as both `label` prop and children
`Fade.edge`	`Fade` is an edge overlay strip on scroll containers, not a content wrapper
`LogoCloud.columns`	Always set `columns` and responsive overrides or logos stack in one column
`StatusIndicator.color`	Uses `color="green"` etc. — not variant or scheme names

Key

Rule

`Icon.names`

Icon names must come from `IconName` in spec.json — never invent

`Badge.duplicate`

Don't pass the same text as both `title` prop and children

`Tag.duplicate`

Don't pass the same text as both `label` prop and children

`Fade.edge`

`Fade` is an edge overlay strip on scroll containers, not a content wrapper

`LogoCloud.columns`

Always set `columns` and responsive overrides or logos stack in one column

`StatusIndicator.color`

Uses `color="green"` etc. — not variant or scheme names

Key	Rule
`layout.shorthands`	Use `fill` not `fillWidth fillHeight`; `center` not `horizontal="center" vertical="center"`; `Row`/`Column` not `Flex direction=`
`layout.defaults`	Never write props equal to defaults: `position="relative"`, `direction` on Row/Column, `variant="primary"` on Button
`section.gaps`	Gap between page sections: 80–160 (typical 104). Inside sections: 24–40. Never 48 between major sections

Key

Rule

`layout.shorthands`

Use `fill` not `fillWidth fillHeight`; `center` not `horizontal="center" vertical="center"`; `Row`/`Column` not `Flex direction=`

`layout.defaults`

Never write props equal to defaults: `position="relative"`, `direction` on Row/Column, `variant="primary"` on Button

`section.gaps`

Gap between page sections: 80–160 (typical 104). Inside sections: 24–40. Never 48 between major sections

Key	Rule
`Card.interactive`	`Card` is for interactive surfaces only (`href` or `onClick`). Static panels use the Column surface recipe
`color.tokens`	Colors are semantic tokens (`{scheme}-{weight}`), never hex/rgb
`color.background-weak`	`*-background-weak` is nearly the page color — use alpha tokens (`brand-alpha-medium`) for glows

Key

Rule

`Card.interactive`

`Card` is for interactive surfaces only (`href` or `onClick`). Static panels use the Column surface recipe

`color.tokens`

Colors are semantic tokens (`{scheme}-{weight}`), never hex/rgb

`color.background-weak`

`*-background-weak` is nearly the page color — use alpha tokens (`brand-alpha-medium`) for glows

Key	Rule
`Background.absolute`	Every absolute decorative layer needs `top="0" left="0"` or it offsets by parent padding
`Background.gradient.width`	Quarter-percent units: 400 = 100%. Soft glows use width 100–200, not 500
`overflow.hero`	`overflow="hidden"` on full-bleed sections clips glows into hard bands

Key

Rule

`Background.absolute`

Every absolute decorative layer needs `top="0" left="0"` or it offsets by parent padding

`Background.gradient.width`

Quarter-percent units: 400 = 100%. Soft glows use width 100–200, not 500

`overflow.hero`

`overflow="hidden"` on full-bleed sections clips glows into hard bands

Key	Rule
`RevealFx.delay`	Delay is in seconds — stagger with `delay={index * 0.1}`, never `index * 80`
`RevealFx.translateY`	Number = rem. Use `translateY={1}` or token `"16"`; bare `16` means 16rem
`CountFx.trigger`	No `trigger` prop — drive `value` from a `useInViewport` latch
`animation.budget`	Entry animation budget: hero + at most 1–2 key moments per page

Key

Rule

`RevealFx.delay`

Delay is in **seconds** — stagger with `delay={index * 0.1}`, never `index * 80`

`RevealFx.translateY`

Number = rem. Use `translateY={1}` or token `"16"`; bare `16` means 16rem

`CountFx.trigger`

No `trigger` prop — drive `value` from a `useInViewport` latch

`animation.budget`

Entry animation budget: hero + at most 1–2 key moments per page

Key	Rule
`Icon.names`	Icon names must come from `IconName` in spec.json — never invent
`Badge.duplicate`	Don't pass the same text as both `title` prop and children
`Tag.duplicate`	Don't pass the same text as both `label` prop and children
`Fade.edge`	`Fade` is an edge overlay strip on scroll containers, not a content wrapper
`LogoCloud.columns`	Always set `columns` and responsive overrides or logos stack in one column
`StatusIndicator.color`	Uses `color="green"` etc. — not variant or scheme names

Key

Rule

`Icon.names`

Icon names must come from `IconName` in spec.json — never invent

`Badge.duplicate`

Don't pass the same text as both `title` prop and children

`Tag.duplicate`

Don't pass the same text as both `label` prop and children

`Fade.edge`

`Fade` is an edge overlay strip on scroll containers, not a content wrapper

`LogoCloud.columns`

Always set `columns` and responsive overrides or logos stack in one column

`StatusIndicator.color`

Uses `color="green"` etc. — not variant or scheme names

Approach	Context cost
Load `gotchas.json` entries for your task	~0.5KB
Load full component doc page	10–50KB
Load `rules.compact.md` + task bundle + targeted gotchas	~4KB total

Common gotchas

Where gotchas live

Layout gotchas

Surface gotchas

Decoration gotchas

Motion gotchas

Component gotchas

Validation workflow

Where gotchas live

Layout gotchas

Surface gotchas

Decoration gotchas

Motion gotchas

Component gotchas

Validation workflow

Context budget tip

Common gotchas

Where gotchas live

Layout gotchas

Surface gotchas

Decoration gotchas

Motion gotchas

Component gotchas

Validation workflow

Where gotchas live

Layout gotchas

Surface gotchas

Decoration gotchas

Motion gotchas

Component gotchas

Validation workflow

Context budget tip

Related