Update SKILL

Author: owjs3901

SKILL.md

@@ -86,16 +86,38 @@ All `@devup-ui/react` components (`Box`, `Flex`, `Text`, etc.) throw `Error('Can
 
 ## Styling APIs
 
+### css() Returns className String (NOT object)
+
 ```tsx
 import { css, styled, globalCss, keyframes } from "@devup-ui/react";
+import clsx from "clsx";
+
+// css() returns a className STRING - use with className prop
+const cardStyle = css({ bg: "white", p: 4, borderRadius: "8px" });
+<Box className={cardStyle} />  // CORRECT
 
-// Reusable style object
-const cardStyles = css({ bg: "white", p: 4, borderRadius: "8px" });
-<Box {...cardStyles} />
+// WRONG - css() is NOT an object to spread
+// <Box {...cardStyle} />  // ERROR!
 
+// Combine multiple styles with clsx
+const baseStyle = css({ p: 4, borderRadius: "8px" });
+const activeStyle = css({ bg: "$primary", color: "white" });
+<Box className={clsx(baseStyle, isActive && activeStyle)} styleOrder={1} />
+
+// styleOrder={1} REQUIRED when mixing className with direct props
+<Box className={cardStyle} bg="$background" styleOrder={1} />
+```
+
+### styled() API
+
+```tsx
 // Styled component (familiar styled-components/Emotion API)
 const Card = styled("div", { bg: "white", p: 4, _hover: { shadow: "lg" } });
+```
+
+### globalCss() and keyframes()
 
+```tsx
 // Global styles
 globalCss({ body: { margin: 0 }, "*": { boxSizing: "border-box" } });
 
@@ -120,7 +142,8 @@ const spin = keyframes({ from: { transform: "rotate(0)" }, to: { transform: "rot
 }
 ```
 
-Use with `$` prefix: `<Box color="$primary" typography="$heading" />`
+Use colors with `$` prefix: `<Box color="$primary" />`
+Use typography without prefix: `<Box typography="heading" />`
 
 Theme API:
 ```tsx
@@ -157,11 +180,47 @@ Options:
 DevupUI({ include: ["@devup/hello"] })  // required to extract and merge their styles
 ```
 
+## $color Token Scope
+
+`$color` tokens only work in **JSX props**. Use `var(--color)` in external objects.
+
+```tsx
+// CORRECT - $color in JSX prop
+<Box bg="$primary" />
+<Box bg={{ active: '$primary', inactive: '$gray' }[status]} />  // inline object OK
+
+// WRONG - $color in external object (won't be transformed)
+const colors = { active: '$primary' }  // '$primary' stays as string literal
+<Box bg={colors.active} />  // broken!
+
+// CORRECT - var(--color) in external object
+const colors = { active: 'var(--primary)' }
+<Box bg={colors.active} />  // works
+```
+
+## Inline Variant Pattern (Preferred)
+
+Use inline object indexing instead of external config objects:
+
+```tsx
+// PREFERRED - inline object indexing
+<Box
+  h={{ lg: '48px', md: '40px', sm: '32px' }[size]}
+  bg={{ primary: '$primary', secondary: '$gray100' }[variant]}
+/>
+
+// AVOID - external config object
+const sizeStyles = { lg: { h: '48px' }, md: { h: '40px' } }
+<Box h={sizeStyles[size].h} />  // unnecessary indirection
+```
+
 ## Anti-Patterns (NEVER do)
 
 | Wrong | Right | Why |
 |-------|-------|-----|
 | `<Box style={{ color: "red" }}>` | `<Box color="red">` | style prop bypasses extraction |
+| `<Box {...css({...})} />` | `<Box className={css({...})} />` | css() returns string, not object |
 | `css({ bg: variable })` | `<Box bg={variable}>` | css()/globalCss() only accept static values |
+| `$color` in external object | `var(--color)` in external object | $color only transformed in JSX props |
 | No build plugin configured | Configure plugin first | Components throw at runtime without transformation |
 | `as any` on style props | Fix types properly | Type errors indicate real issues |