@zvoove/unity-ui 2.21.0 → 2.22.0

package/dist/llms.txt

@@ -1075,6 +1075,263 @@ useClickOutside(ref, () => setOpen(false), isOpen);
 
 ---
 
+## STYLING
+
+When a UI element has no matching Unity UI component, use **Tailwind CSS v4** with the Unity UI design tokens. **Never use inline styles or arbitrary CSS values.**
+
+### Setup
+
+```bash
+npm install tailwindcss tailwind-variants tailwind-merge
+```
+
+In your Tailwind CSS entry file:
+```css
+@import 'tailwindcss';
+@import '@zvoove/unity-ui/theme.css';  /* registers all design tokens as Tailwind utilities */
+```
+
+### Design Tokens as Tailwind Classes
+
+All tokens from `theme.css` are available as Tailwind utilities. Use **semantic** tokens, not raw palette tokens.
+
+**Colors (semantic — always prefer these)**
+| Token | Tailwind utility | Use for |
+|-------|-----------------|---------|
+| `--color-primary` | `bg-primary` / `text-primary` / `border-primary` | Primary brand color |
+| `--color-on-primary` | `text-on-primary` | Text on primary backgrounds |
+| `--color-surface` | `bg-surface` | Card/panel backgrounds |
+| `--color-surface-container` | `bg-surface-container` | Nested container backgrounds |
+| `--color-on-surface` | `text-on-surface` | Body text |
+| `--color-on-surface-variant` | `text-on-surface-variant` | Secondary/muted text |
+| `--color-outline` | `border-outline` | Default borders |
+| `--color-outline-variant` | `border-outline-variant` | Subtle dividers |
+| `--color-error` | `bg-error` / `text-error` | Error states |
+| `--color-background` | `bg-background` | Page background |
+
+**Spacing** (for gap, padding, margin, width, height)
+`none`(0) • `xs2`(4px) • `xs`(8px) • `sm`(12px) • `md`(16px) • `lg`(20px) • `xl`(24px) • `xl2`(32px) • `xl3`(40px) • `xl4`(48px) • `xl5`(64px) • `xl6`(80px) • `xl7`(96px)
+
+Examples: `p-md`, `gap-lg`, `mx-xl`, `w-xl4`
+
+**Typography**
+`text-body-small` • `text-body-medium` • `text-body-large`
+`text-label-small` • `text-label-medium` • `text-label-large`
+`text-title-small` • `text-title-medium` • `text-title-large`
+`text-headline-small` • `text-headline-medium` • `text-headline-large`
+`text-display-small` • `text-display-medium` • `text-display-large`
+
+**Border radius**: `rounded-none` • `rounded-xs` • `rounded-sm` • `rounded-md` • `rounded-lg` • `rounded-xl` • `rounded-full`
+
+**Shadows**: `shadow-elevation1` • `shadow-elevation2` • `shadow-elevation3` • `shadow-elevation4` • `shadow-elevation5`
+Dark mode shadows: `dark:shadow-elevation1-dark` (replace `elevation1` with the level you need)
+
+**Dark mode**: use `dark:` Tailwind prefix. Activated by `data-theme="dark"` on a parent element — not via `prefers-color-scheme`.
+
+### tailwind-variants for Component Variants
+
+Use `tailwind-variants` when a custom UI element has multiple visual variants.
+
+Configure `tv` with Unity UI spacing tokens so class merging works correctly:
+```ts
+import { createTV } from 'tailwind-variants';
+
+export const tv = createTV({
+  twMergeConfig: {
+    theme: {
+      spacing: ['none', 'xs2', 'xs', 'sm', 'md', 'lg', 'xl', 'xl2', 'xl3', 'xl4', 'xl5', 'xl6', 'xl7'],
+      borderRadius: ['none', 'xs', 'sm', 'md', 'lg', 'xl', 'full'],
+    },
+  },
+});
+```
+
+Usage:
+```ts
+const badge = tv({
+  base: ['inline-flex', 'items-center', 'rounded-full', 'px-sm', 'py-xs2', 'text-label-small'],
+  variants: {
+    tone: {
+      primary: ['bg-primary-container', 'text-on-primary-container'],
+      error:   ['bg-error-container',   'text-on-error-container'],
+      surface: ['bg-surface-container', 'text-on-surface'],
+    },
+  },
+  defaultVariants: { tone: 'surface' },
+});
+
+// Apply:
+<div className={badge({ tone: 'primary' })}>Label</div>
+```
+
+### Class Merging
+
+Use `tailwind-merge` for ad-hoc merging (e.g. accepting a `className` prop):
+```ts
+import { twMerge } from 'tailwind-merge';
+
+const className = twMerge('p-md bg-surface', props.className);
+```
+
+### Rules
+
+- NEVER use inline styles: `style={{ color: '#ff0000', padding: '13px' }}`
+- NEVER use arbitrary Tailwind values: `p-[13px]`, `text-[#ff0000]`, `bg-[rgba(0,0,0,0.5)]`
+- NEVER use generic Tailwind size utilities for spacing — use design tokens: `p-md` not `p-4`
+- NEVER use generic Tailwind text utilities for typography — use design tokens: `text-body-medium` not `text-sm`
+- ALWAYS use semantic color tokens (`bg-primary`, `text-on-surface`) not palette tokens (`bg-primary-40`)
+- Use `tv()` from `tailwind-variants` when a custom element has multiple visual variants
+- Use `dark:` prefix for dark mode — never hard-code colors per theme in two separate class sets
+
+---
+
+## CUSTOM COMPONENT
+
+When you need UI that no existing Unity UI component covers, create a custom component that follows the same conventions so it stays consistent with the design system.
+
+### File Structure
+
+```
+src/components/MyComponent/
+  MyComponent.tsx         # Component implementation
+  MyComponent.styled.ts   # tailwind-variants styles
+  MyComponent.types.ts    # TypeScript props interface
+  MyComponent.test.tsx    # Vitest + RTL tests (optional but recommended)
+  index.ts                # Re-exports
+```
+
+### `MyComponent.types.ts`
+
+```ts
+import { ReactNode } from 'react';
+
+export interface MyComponentProps {
+  /**
+   * Content to render inside the component.
+   */
+  children?: ReactNode;
+
+  /**
+   * Visual variant.
+   * @default 'primary'
+   */
+  variant?: 'primary' | 'secondary';
+}
+```
+
+Rules:
+- JSDoc on every prop; `@default` on every defaulted prop
+- Named export only
+
+### `MyComponent.styled.ts`
+
+```ts
+import { createTV } from 'tailwind-variants';
+
+// Configure tv with Unity UI spacing/radius tokens for correct class merging
+const tv = createTV({
+  twMergeConfig: {
+    theme: {
+      spacing: ['none', 'xs2', 'xs', 'sm', 'md', 'lg', 'xl', 'xl2', 'xl3', 'xl4', 'xl5', 'xl6', 'xl7'],
+      borderRadius: ['none', 'xs', 'sm', 'md', 'lg', 'xl', 'full'],
+    },
+  },
+});
+
+export const myComponentStyles = tv({
+  base: ['text-body-medium', 'rounded-sm'],
+  variants: {
+    variant: {
+      primary: ['bg-primary', 'text-on-primary'],
+      secondary: ['bg-surface-container', 'text-on-surface'],
+    },
+  },
+  defaultVariants: {
+    variant: 'primary',
+  },
+});
+```
+
+Tip: define the configured `tv` once in a shared `lib/tv.ts` file in your project and import from there instead of re-configuring in every component.
+
+### `MyComponent.tsx` — Simple
+
+```tsx
+import { myComponentStyles } from './MyComponent.styled';
+import { MyComponentProps } from './MyComponent.types';
+
+const MyComponent = ({
+  children,
+  variant = 'primary',
+}: MyComponentProps) => {
+  return (
+    <div className={myComponentStyles({ variant })}>
+      {children}
+    </div>
+  );
+};
+
+MyComponent.displayName = 'MyComponent';
+
+export default MyComponent;
+```
+
+### `MyComponent.tsx` — With `forwardRef`
+
+Use when the root is a DOM element consumers may need a ref for:
+
+```tsx
+import { forwardRef } from 'react';
+
+import { myComponentStyles } from './MyComponent.styled';
+import { MyComponentProps } from './MyComponent.types';
+
+const MyComponent = forwardRef<HTMLDivElement, MyComponentProps>(
+  ({ children, variant = 'primary', ...props }, ref) => {
+    return (
+      <div
+        ref={ref}
+        className={myComponentStyles({ variant })}
+        {...props}
+      >
+        {children}
+      </div>
+    );
+  }
+);
+
+MyComponent.displayName = 'MyComponent';
+
+export default MyComponent;
+```
+
+### `index.ts`
+
+```ts
+export { default as MyComponent } from './MyComponent';
+export type { MyComponentProps } from './MyComponent.types';
+```
+
+### Using Unity UI Components Inside Custom Components
+
+```tsx
+import { Icon, Stack, Typography } from '@zvoove/unity-ui';
+```
+
+Always compose with existing Unity UI components rather than re-implementing their functionality.
+
+### Rules
+
+- Always set `ComponentName.displayName = 'ComponentName'`
+- Always JSDoc every prop with `@default` on defaulted props
+- Use `tv()` from `tailwind-variants` (configured with Unity UI tokens — see `unity-ui-styling` skill)
+- Use design tokens as Tailwind utilities — no arbitrary values, no inline styles
+- Use `forwardRef` when the root is a DOM element that callers may need to reference
+- Import Unity UI components from `@zvoove/unity-ui`
+- Never recreate what an existing Unity UI component already does
+
+---
+
 ## SPACING SCALE
 
 Use these values for gap, padding, and margin props: