디자인 규칙

/opt-ui-guide 스킬 스캔

Every interactive element (`<button>`, `<a>`, `Button`, `MenuItem`, …) must expose an accessible name via visible text children, `aria-label`, or `aria-labelledby` pointing at a visible element.

<button onClick={handleClick}>
  <IconTrash />
</button>

<button onClick={handleClick} aria-label="Delete item">
  <IconTrash />
</button>

검출 Find `<button`, primitive button wrappers, and `<a ` elements. Check for text children, `aria-label`, or `aria-labelledby`. Icon-only buttons (children is only a component starting with `Icon` or `<svg>`) without `aria-label` trigger this rule.

/opt-ui-guide 스킬 스캔

All `<img>` elements must have `alt`. Decorative images use `alt=""` or `aria-hidden="true"`. SVGs used as icons must be `aria-hidden="true"`.

<img src="/logo.png" />
<svg viewBox="0 0 24 24">...</svg>

<img src="/logo.png" alt="Company logo" />
<svg viewBox="0 0 24 24" aria-hidden="true">...</svg>

검출 Find `<img` without `alt`. Find `<svg` without `aria-hidden` that is not inside a labeled button.

/opt-ui-guide 스킬 스캔

Every `<input>`, `<select>`, `<textarea>`, and opt-ui form control must have a `<label>` with matching `htmlFor`/`id`, an `aria-label`, or an `aria-labelledby`.

<input type="text" placeholder="Search..." />

<label htmlFor="search">Search</label>
<input id="search" type="text" placeholder="Search..." />

검출 Find `<input`, `<select`, `<textarea` elements. Check for a `<label htmlFor=` matching the `id`, or `aria-label`/`aria-labelledby` on the element. An opt-ui `<FormInput>` with a `name` prop that has a corresponding `<FormLabel>` is acceptable.

/opt-ui-guide 스킬 스캔

Error messages tied to a form input must be linked via `aria-describedby` and carry `role="alert"` so they are announced.

<input />
{error && <span className="text-red-500">{error}</span>}

<input aria-invalid={!!error} aria-describedby="email-error" />
{error && (
  <span id="email-error" role="alert">
    {error}
  </span>
)}

검출 Find an error `<span>`/`<p>` rendered near an input where the input has no `aria-describedby` pointing at the error element's `id`.

/opt-ui-guide 스킬 스캔

Custom widgets must declare their role explicitly when HTML semantics do not convey it: toggle → `role="switch"`, tab panel → `role="tabpanel"`, status indicator → `role="status"`, alert → `role="alert"`.

예외 opt-ui primitives with built-in roles are exempt.

검출 Look for components rendering `<div>`/`<span>` with toggle, switch, or status behavior but no `role` attribute.

Oxlint opt-ui/no-outline-none-without-focus-visible — bun run lint가 차단

All interactive elements need visible focus indication. Use `focus-visible:ring-2 focus-visible:ring-blue-600` or `data-[focus-visible]:outline-2 data-[focus-visible]:outline-blue-600`.

Do NOT use `focus:` — use `focus-visible:` so mobile taps do not flash a focus ring.

<button className="outline-none">Click</button>

<button className="outline-none focus-visible:ring-2 focus-visible:ring-blue-600">
  Click
</button>

검출 Find interactive elements with `outline-none` but no `focus-visible:` or `data-[focus-visible]:` styles. Primitives that receive focus tokens (`OPT_FOCUS`, `OPT_FOCUS_VISIBLE`) via `cn()` are acceptable.

/opt-ui-guide 스킬 스캔

Non-button elements with `onClick` must also handle `onKeyDown` for Enter/Space, or use a semantic element (`<button>`, `<a>`, `Button`).

<div onClick={handleClick}>Clickable area</div>

<button onClick={handleClick}>Clickable area</button>

검출 Find `<div`/`<span` with `onClick` and no `onKeyDown`. Overlaps X01, but A07 is specifically about keyboard equivalence.

/opt-ui-guide 스킬 스캔

Status indicators conveyed only by color (green/red/yellow dots) must also provide text or an `aria-label` for colorblind users.

<span className="h-2 w-2 rounded-full bg-green-500" />

<span className="h-2 w-2 rounded-full bg-green-500" aria-label="Active" />

검출 Find elements with only dot-style classes (`h-2 w-2 rounded-full bg-{color}-500`) and no `aria-label` or adjacent text.

/opt-ui-guide 스킬 스캔

Dialogs and modals must trap focus. Use opt-ui's `Dialog`, which handles this automatically.

검출 Find a raw `<div>` rendered as a modal (`fixed inset-0` or a portal) without opt-ui `Dialog`. Hand-rolled focus traps are acceptable but should be flagged as `info`.

/opt-ui-guide 스킬 스캔

Page-level Blocks should use landmark regions (`<main>`, `<nav>`, `<aside>`, `<header>`, `<footer>`) or provide a skip link.

검출 In Block files, check for at least one landmark element or equivalent `role` (`role="main"`, `role="navigation"`).

/opt-ui-guide 스킬 스캔

Components must not skip heading levels — an `<h1>` followed by `<h3>` with no `<h2>` between them.

검출 Collect `<h1>`–`<h6>` in the file and check for skipped levels.

/opt-ui-guide 스킬 스캔

Content that updates dynamically (status changes, loading states, notifications) should use `aria-live="polite"` or `aria-live="assertive"`.

검출 Find conditional rendering of status text or notifications where the container has no `aria-live`.

Oxlint opt-ui/no-legacy-tokens — bun run lint가 차단

Legacy token constants are retired. Import the `OPT_*` design tokens instead so themes stay in sync.

Oxlint opt-ui/no-zinc-colors — bun run lint가 차단

Replace hardcoded `zinc-*` colors with opacity-based equivalents.

<div className="text-zinc-700 dark:text-zinc-300">

<div className="text-black/80 dark:text-white/80">

검출 Regex for `zinc-\d{2,3}` in className strings and template literals.

/opt-ui-guide 스킬 스캔

Dark mode backgrounds use `bg-surface`, not a hardcoded HSL or `zinc-900`. The default dark theme defines distinct base, raised, and overlay surface levels, and semantic utilities keep consumers aligned when those values change.

<div className="bg-white dark:bg-zinc-900">

<div className="bg-white dark:bg-surface">

검출 Find `dark:bg-zinc-900` in className strings.

Oxlint opt-ui/prefer-blue-600-focus — bun run lint가 차단

Focus indicators use `blue-600`, not `blue-500`, to match the opt-ui focus color.

focus-visible:ring-blue-500

focus-visible:ring-blue-600

검출 Find `blue-500` in focus-related classes (`ring-blue-500`, `outline-blue-500`).

/opt-ui-guide 스킬 스캔

Borders use the opacity-based pattern so they hold up across themes.

border-zinc-200 dark:border-zinc-700

border-border

검출 Find `border-zinc-` patterns in className strings.

/opt-ui-guide 스킬 스캔

Use a consistent border radius per element type within a file.

검출 Collect all `rounded-*` classes and flag files that mix `rounded-lg` and `rounded-md` for the same kind of element.

/opt-ui-guide 스킬 스캔

Every `dark:` utility needs a corresponding light-mode class. An unpaired dark class means the light theme was never styled.

<div className="dark:text-white/80">

<div className="text-black/80 dark:text-white/80">

예외 `dark:ring-offset-*` and `dark:placeholder:*` may stand alone.

검출 Find `dark:` prefixed classes and verify a non-dark equivalent exists on the same element.

/opt-ui-guide 스킬 스캔

If the same Tailwind class combination appears three or more times in a file, extract it to a local constant or import an existing token.

검출 Find className strings that repeat the same 3+ class combination more than twice.

/opt-ui-guide 스킬 스캔

Avoid arbitrary color values (`bg-[#ff0000]`, `text-[rgb(255,0,0)]`). Use design system colors (blue, red, emerald, amber) or opacity-based tokens.

예외 HSL dark mode backgrounds `hsl(204 4% *)` are acceptable.

검출 Find `[#`, `[rgb`, or `[hsl` in className strings, excluding the standard dark-mode HSL values.

/opt-ui-guide 스킬 스캔

Avoid the `!important` modifier. If specificity fights you, restructure the component instead.

<div className="!text-red-500">

<div className="text-red-500">

검출 Find a `!` prefix on Tailwind class names within className strings.

Oxlint opt-ui/prefer-semantic-spacing (advisory — CI에서 off, 스킬이 검사)

Use semantic spacing tokens instead of raw numeric values so spacing stays consistent across themes.

CSS variables: `--opt-space-section` (1.5rem), `--opt-space-group` (1rem), `--opt-space-element` (0.5rem).

<div className="space-y-6">

<div className="flex flex-col gap-section">

검출 Find `gap-4`, `gap-6`, `gap-8`, `space-y-4`, `space-y-6`, `space-y-8` in className strings and suggest semantic equivalents.

Oxlint opt-ui/no-space-y (advisory — CI에서 off, 스킬이 검사)

`space-y-*` and `space-x-*` compile to the `> * + *` selector, which only applies margin between direct sibling children. Wrap the content in a single element and the spacing silently becomes zero.

Always use `flex` plus `gap-*` instead.

<div className="space-y-6">

<div className="flex flex-col gap-section">

검출 Find `space-y-` or `space-x-` in className strings, template literals, and `cn()` arguments.

Oxlint opt-ui/no-raw-color (advisory — CI에서 off, 스킬이 검사)

Raw color utilities (`text-white`, `bg-amber-500`, and the rest of the Tailwind palette) bypass theming. Use semantic tokens — `text-accent-fg`, `text-danger-fg`, `text-text-{primary,secondary,tertiary}`, `bg-surface` — or their alpha aliases such as `text-accent-fg/60`.

For composite item active state, drive children from `OPT_ACTIVE_ITEM` (`lib/styles.ts`) with `data-[active-item]:text-accent-fg/{N}` or `bg-accent-fg/{N}`.

Intentional exceptions (`text-white` over a saturated badge background, marquee selection, padding visualisation) need an inline suppression with a reason.

검출 The `dark:` prefix is allowed automatically; other raw palette classes are reported.

Oxlint opt-ui/no-div-onclick — bun run lint가 차단

Never use `<div>` or `<span>` as a clickable element. Non-semantic interactive elements are invisible to screen readers and unreachable by keyboard — use `<button>`, `<a>`, or an accessible component.

<div onClick={handleClick} className="cursor-pointer">
  Click me
</div>

<button onClick={handleClick}>
  Click me
</button>

예외 `<div onClick>` inside a `role="grid"` or composite context where a framework manages keyboard navigation.

검출 Find `<div`/`<span` with an `onClick` prop, excluding elements carrying `role="button"`, `role="option"`, `role="tab"`, or `role="gridcell"`.

/opt-ui-guide 스킬 스캔

`cursor-pointer` on a `<div>` or `<span>` is a code smell: the element should be a button. If it really is non-interactive, drop the class.

<div className="cursor-pointer" onClick={handleClick}>

<button className="cursor-pointer" onClick={handleClick}>

검출 Find `cursor-pointer` in className on `<div`/`<span` elements.

/opt-ui-guide 스킬 스캔

In the rare case `onClick` must live on a non-button element, it needs `role="button"` (or the appropriate role), `tabIndex={0}`, and an `onKeyDown` handler for Enter/Space.

<div onClick={handleClick}>

<div role="button" tabIndex={0} onClick={handleClick} onKeyDown={handleKeyDown}>

검출 Find `<div`/`<span` with `onClick` and no `role` attribute.

Oxlint opt-ui/prefer-primitives-form (advisory — CI에서 off, 스킬이 검사)

Use the opt-ui `Form` primitives rather than a raw `<form>`, so validation, labelling, and submission stay consistent.

Oxlint opt-ui/no-mixed-tokens — bun run lint가 차단

Mixing legacy token constants with `OPT_*` tokens in one file produces inconsistent theming. Migrate the file wholesale.

Oxlint opt-ui/require-labels-no-hardcode (advisory — CI에서 off, 스킬이 검사)

User-facing copy belongs in a `Labels` interface so consumers can translate it.

Oxlint opt-ui/no-console-log — bun run lint가 차단

Remove `console.log`, `console.debug`, and `console.info`. `console.warn` and `console.error` are fine for genuine warnings and failures.

console.log("render count:", count);

console.warn("Deprecated prop used");
console.error("Failed to load data", error);

검출 Find `console.log(`, `console.debug(`, `console.info(` in non-test files.

/opt-ui-guide 스킬 스캔

Avoid `as any`, `: any`, and `any[]`. Model the type properly, or use `unknown` with a type guard.

const data = response as any;
function process(items: any[]) { ... }

const data = response as ApiResponse;
function process(items: unknown[]) { ... }

검출 Find `as any`, `: any`, `any[]`, `any>`, `<any` in TypeScript code, excluding comments.

Oxlint opt-ui/require-suppress-explanation (advisory — CI에서 off, 스킬이 검사)

Every suppression comment must say why the suppression is needed.

Prefer `@ts-expect-error` over `@ts-ignore` — it errors once the suppression is no longer needed.

// oxlint-disable-next-line
// @ts-ignore

// oxlint-disable-next-line react/exhaustive-deps -- intentionally empty deps
// @ts-expect-error -- type mismatch, fixed in next version

검출 Find `oxlint-disable`, `@ts-ignore`, `@ts-expect-error` comments and check for explanatory text after `--` or on the same line.

Oxlint opt-ui/no-deep-ternary (advisory — CI에서 off, 스킬이 검사)

Ternaries nested three or more levels deep are hard to read. Use early returns, `if`/`else`, or a lookup object.

const color =
  status === "active"
    ? type === "admin"
      ? role === "super"
        ? "blue"
        : "green"
      : "yellow"
    : "gray";

function getColor(status: string, type: string, role: string) {
  if (status !== "active") return "gray";
  if (type !== "admin") return "yellow";
  return role === "super" ? "blue" : "green";
}

검출 Count ternary nesting depth and flag at depth 3 or more.

Oxlint opt-ui/no-deprecated-api — bun run lint가 차단

Components and props carrying a `deprecated` notice in `component-catalog.json` must not be used in new code. The notice names the replacement.

The rule is generated from component metadata: adding `deprecated` to a `ComponentMeta` or `PropDef` is the only step needed to start blocking a usage.

<Switch label="알림" description="설명 텍스트" />

<Switch label="알림" hint="설명 텍스트" />

검출 Resolve each JSX element back to the `@reopt-ai/opt-*` export it was imported from, then look the component and its props up in the catalog.

Oxlint opt-ui/no-upward-imports — bun run lint가 차단

Imports flow Core → Shells → Blocks and never the other way. A Core component may not import from `shells/`.

Oxlint opt-ui/no-cross-package-import — bun run lint가 차단

opt-ui must not import from the retired opt-ui-surface package.

Oxlint opt-ui/require-use-client (advisory — CI에서 off, 스킬이 검사)

Files using React hooks, `forwardRef`, `createContext`, `memo`, `lazy`, inline JSX event handlers, or function props need a `"use client"` directive at the top.

Oxlint opt-ui/no-unnecessary-use-client (advisory — CI에서 off, 스킬이 검사)

Static components stay server-safe so the RSC tree keeps its efficiency. Remove `"use client"` where no interactive pattern is present.

Oxlint opt-ui/props-naming (advisory — CI에서 off, 스킬이 검사)

A component's props interface is named after the component.

Oxlint opt-ui/require-display-name (advisory — CI에서 off, 스킬이 검사)

Without `displayName`, React DevTools shows the component as anonymous.

Oxlint opt-ui/require-labels (advisory — CI에서 off, 스킬이 검사)

Every user-facing string is injectable through a `Labels` interface for i18n.

Oxlint opt-ui/require-empty-state (advisory — CI에서 off, 스킬이 검사)

A component that renders a collection must render something when it is empty.

테스트 — packages/opt-ui/src/__tests__/meta-source-files.test.ts

A component not exported from the barrel is unreachable by consumers.

Oxlint opt-ui/require-block-layout — bun run lint가 차단

A Block root must use `BlockLayout` (or `createBlock`) rather than applying `space-y-*`/`gap-*` directly.

Oxlint opt-ui/block-loading-prop (advisory — CI에서 off, 스킬이 검사)

A Block owns its loading presentation, so it must accept `loading`.

Oxlint opt-ui/block-slots (advisory — CI에서 off, 스킬이 검사)

Blocks expose `header` and `actions` slots so pages can compose around them.

Oxlint opt-ui/require-export-jsdoc (advisory — CI에서 off, 스킬이 검사)

Exported functions, interfaces, and types document what they are for.

Oxlint opt-ui/require-opt-id (advisory — CI에서 off, 스킬이 검사)

`data-opt-id` identifies a component instance for devtools and E2E targeting. Scheduled for promotion to `error`.

코드 리뷰

Expand/collapse should run through `animated` (`data-[enter]`/`data-[leave]`).

코드 리뷰

A transition defined only for enter snaps on the way out.

코드 리뷰

Floating surfaces need a 4–8px `gutter` so they do not touch their trigger.

코드 리뷰

A fresh object literal each render defeats memoisation — hoist it or use `useMemo`.

코드 리뷰

Data that never changes should not be rebuilt inside the component body.

코드 리뷰

An unstable handler identity re-renders the memoized child on every parent render.