@orioncactuscorp/ui 1.10.0 → 1.12.0

package/docs/typography.md

@@ -0,0 +1,115 @@
+# Typography
+
+oc-ui typography foundation은 19개 variant와 `normal | medium | bold` weight 조합을 제공합니다. variant 이름은 정보 위계와 읽기 맥락의 계약이고, size·line-height 값은 responsive profile과 consumer override에 따라 달라질 수 있는 기본값입니다.
+
+## Variant hierarchy
+
+- `display1`~`display3`: 캠페인 hero나 대형 숫자처럼 짧고 가장 강한 표현
+- `title1`~`title3`: 페이지 표제
+- `heading1`~`heading2`: 큰 section의 제목
+- `headline1`~`headline2`: 내비게이션과 소섹션(sub-section)의 제목
+- `body1`~`body2`: 일반 본문과 UI 설명. `body1`이 기본 페이지 typography
+- `label1`~`label2`: 대상을 지칭하는 '라벨' 텍스트 — form field label, 항목명, button·menu 같은 control의 라벨
+- `caption1`~`caption2`: metadata, timestamp, 짧은 보조 정보
+
+variant 숫자가 작을수록 같은 계층 안에서 더 큽니다. 계층을 오직 크기 선택 도구로 사용하지 말고 문서 구조와 UI 역할에 맞춰 선택합니다.
+
+## Reading variants
+
+`body1reading`, `body2reading`, `label1reading`은 대응 기본 variant와 font-size·letter-spacing·weight가 같고 line-height만 더 넓습니다. 여러 줄로 이어지는 본문, 안내문, 조밀한 label 묶음처럼 읽기 호흡이 필요한 경우에 사용합니다. 한 줄 control label이나 짧은 badge에는 기본 variant를 유지합니다.
+
+## Responsive stops
+
+기본 profile은 `sm / md / lg / xl` 4개 stop을 사용합니다.
+
+- `body*`, `label*`, `caption*`은 `md` stop을 포함합니다.
+- `heading*`, `headline*`, `body*`, `label*`, `caption*`은 `xl` stop을 포함합니다.
+- `display*`, `title*`은 `sm / lg`, `heading*`과 `headline*`은 `sm / lg / xl` 기본값을 가집니다.
+- 정의되지 않은 stop은 responsive segment에서 인접한 유효 stop을 기준으로 보간·유지됩니다. 표의 `—`는 token이 없다는 뜻이 아니라 해당 variant map에 별도 stop 값이 없다는 뜻입니다.
+
+## Weight policy
+
+모든 variant는 `normal`, `medium`, `bold` 세 이름을 제공하지만 `bold`의 숫자는 계층에 따라 낮아집니다. display·title은 700, heading·headline·body는 600, label은 550, caption1은 540, caption2는 530입니다. 작은 글자에서 지나치게 뭉치는 것을 피하면서 의미상 같은 `bold` 역할을 유지하기 위한 정책입니다.
+
+## 기본값 표
+
+<!-- prettier-ignore-start -->
+<!-- generated:typography:start -->
+> 아래 표는 기본 responsive profile의 SCSS map에서 생성됩니다. 값은 고정 스펙이 아니라 기본값입니다. line-height 괄호 안 숫자는 `line-height / font-size` 비율입니다.
+
+| Variant | Size sm | Size md | Size lg | Size xl | Line-height sm | Line-height md | Line-height lg | Line-height xl | Letter spacing | Normal | Medium | Bold |
+| --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
+| `display1` | 48px | — | 64px | — | 62px (1.29) | — | 82px (1.28) | — | 0em | 400 | 500 | 700 |
+| `display2` | 40px | — | 48px | — | 52px (1.30) | — | 62px (1.29) | — | 0em | 400 | 500 | 700 |
+| `display3` | 36px | — | 40px | — | 48px (1.33) | — | 52px (1.30) | — | 0em | 400 | 500 | 700 |
+| `title1` | 32px | — | 36px | — | 44px (1.38) | — | 48px (1.33) | — | 0em | 400 | 500 | 700 |
+| `title2` | 28px | — | 32px | — | 38px (1.36) | — | 42px (1.31) | — | 0em | 400 | 500 | 700 |
+| `title3` | 24px | — | 28px | — | 32px (1.33) | — | 36px (1.29) | — | 0em | 400 | 500 | 700 |
+| `heading1` | 22px | — | 24px | 26px | 30px (1.36) | — | 32px (1.33) | 34px (1.31) | 0em | 400 | 500 | 600 |
+| `heading2` | 20px | — | 22px | 24px | 28px (1.40) | — | 30px (1.36) | 32px (1.33) | 0em | 400 | 500 | 600 |
+| `headline1` | 18px | — | 20px | 22px | 26px (1.44) | — | 28px (1.40) | 30px (1.36) | 0em | 400 | 500 | 600 |
+| `headline2` | 17px | — | 18px | 20px | 24px (1.41) | — | 26px (1.44) | 28px (1.40) | 0em | 400 | 500 | 600 |
+| `body1` | 16px | 17px | 18px | 20px | 24px (1.50) | 26px (1.53) | 28px (1.56) | 30px (1.50) | 0em | 400 | 500 | 600 |
+| `body1reading` | 16px | 17px | 18px | 20px | 26px (1.63) | 28px (1.65) | 30px (1.67) | 32px (1.60) | 0em | 400 | 500 | 600 |
+| `body2` | 15px | 16px | 17px | 18px | 22px (1.47) | 24px (1.50) | 26px (1.53) | 28px (1.56) | 0em | 400 | 500 | 600 |
+| `body2reading` | 15px | 16px | 17px | 18px | 24px (1.60) | 26px (1.63) | 28px (1.65) | 30px (1.67) | 0em | 400 | 500 | 600 |
+| `label1` | 14px | 15px | 16px | 17px | 20px (1.43) | 22px (1.47) | 24px (1.50) | 26px (1.53) | 0.01em | 400 | 500 | 550 |
+| `label1reading` | 14px | 15px | 16px | 17px | 22px (1.57) | 24px (1.60) | 26px (1.63) | 28px (1.65) | 0.01em | 400 | 500 | 550 |
+| `label2` | 13px | 14px | 15px | 16px | 18px (1.38) | 20px (1.43) | 22px (1.47) | 24px (1.50) | 0.01em | 400 | 500 | 550 |
+| `caption1` | 12px | 13px | 14px | 15px | 16px (1.33) | 18px (1.38) | 20px (1.43) | 22px (1.47) | 0.01em | 400 | 500 | 540 |
+| `caption2` | 11px | 12px | 13px | 14px | 14px (1.27) | 16px (1.33) | 18px (1.38) | 20px (1.43) | 0.01em | 400 | 500 | 530 |
+<!-- generated:typography:end -->
+<!-- prettier-ignore-end -->
+
+## Usage
+
+raw `--oc-typo-size-*`, `--oc-typo-height-*`, `--oc-typo-spacing-*`, `--oc-typo-weight-*`를 직접 조합하지 말고 반드시 `typo()` mixin을 사용합니다. mixin은 네 속성을 같은 variant contract에서 출력하고 runtime `--oc-typo-size-factor`도 반영합니다.
+
+```scss
+@use '@orioncactuscorp/ui/scss/mixins/typo' as *;
+
+.pageTitle {
+  @include typo(title1, bold);
+}
+
+.articleBody {
+  @include typo(body1reading, normal);
+}
+
+.fieldLabel {
+  @include typo(label1, medium);
+}
+```
+
+## Customize
+
+### Size and line-height maps
+
+foundation을 직접 compile할 때 `$oc-typo-size-overrides`와 `$oc-typo-height-overrides`로 필요한 variant·stop만 덮습니다. 역할 이름은 유지하고 제품에 필요한 기본값만 조정합니다.
+
+```scss
+@use '@orioncactuscorp/ui/scss/foundations/typo' as * with (
+  $oc-typo-size-overrides: (
+    title1: (
+      sm: 36,
+    ),
+  ),
+  $oc-typo-height-overrides: (
+    title1: (
+      sm: 48,
+    ),
+  )
+);
+```
+
+### Runtime size factor
+
+`--oc-typo-size-factor`는 size와 line-height에 함께 적용되는 runtime multiplier입니다. 특정 subtree의 접근성 확대나 preview에 사용할 수 있지만, variant 간 위계를 다시 설계하는 용도로 남용하지 않습니다.
+
+```css
+.largeTypeScope {
+  --oc-typo-size-factor: 1.125;
+}
+```
+
+fluid·stepped·static 출력과 active stop 범위는 [Responsive Foundation Profile](./responsive-foundation-profile.md), mixin signature는 [SCSS Helpers](./scss-helpers.md)를 참조하세요. Storybook typography matrix는 현재 foundation profile의 CSS variable을 사용하므로 override 환경의 실값을 그대로 보여줍니다.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orioncactuscorp/ui",
-  "version": "1.10.0",
+  "version": "1.12.0",
   "description": "orioncactus UI foundations and core primitives",
   "private": false,
   "type": "module",
@@ -31,6 +31,7 @@
   "files": [
     "dist",
     "src/scss",
+    "docs",
     "README.md",
     "LICENSE"
   ],
@@ -78,14 +79,18 @@
   },
   "packageManager": "bun@1.3.6",
   "scripts": {
-    "build": "bun run build:lib && bun run build:css && bun run check:exports && bun run check:dist-imports && bun run check:rsc-boundaries",
+    "build": "bun run build:lib && bun run build:css && bun run check:exports && bun run check:dist-imports && bun run check:css-injection && bun run check:rsc-boundaries",
     "build:lib": "vite build && node scripts/preserve-client-directives.mjs",
-    "build:css": "sass src/scss/foundations:dist/foundations --no-source-map --style=compressed && node scripts/fix-css-module-artifacts.mjs && node scripts/bundle-foundations.mjs && node scripts/generate-vscode-css-vars.mjs",
+    "build:css": "sass src/scss/foundations:dist/foundations --no-source-map --style=compressed && node scripts/fix-css-module-artifacts.mjs && node scripts/bundle-foundations.mjs && node scripts/generate-vscode-css-vars.mjs && node scripts/generate-token-reference.mjs",
+    "docs:tokens": "node scripts/generate-token-reference.mjs",
+    "docs:tokens:check": "node scripts/generate-token-reference.mjs --check",
     "check:exports": "node scripts/check-package-exports.mjs",
     "check:dist-imports": "node scripts/check-dist-imports.mjs",
+    "check:css-injection": "node scripts/check-css-injection.mjs",
     "check:rsc-boundaries": "node scripts/check-rsc-client-boundaries.mjs",
     "test": "vitest",
-    "test:run": "vitest run",
+    "test:run": "vitest run && node --test scripts/*.test.mjs",
+    "test:scripts": "node --test scripts/*.test.mjs",
     "test:coverage": "vitest run --coverage",
     "test:e2e": "bun run --cwd ../.. build && bun run --cwd ../.. example:build && playwright test",
     "test:e2e:ci": "bun run --cwd ../.. example:build && playwright test",

package/src/scss/foundations/color-theme.test.ts

@@ -30,11 +30,37 @@ describe('color theme foundations', () => {
     `);
 
     expect(css).toMatch(
-      /:root\{[^}]*--oc-color-theme-background-normal-normal:var\(--oc-color-global-common-100\)/,
+      /:root\{color-scheme:light;[^}]*--oc-color-theme-background-normal-normal:var\(--oc-color-global-common-100\)/,
+    );
+    expect(css).toContain('[data-theme=light]{color-scheme:light;');
+    expect(css).toContain(
+      '@media(prefers-color-scheme:dark){:root:where(:not([data-theme=light])){color-scheme:dark;',
+    );
+    expect(css).toContain('[data-theme=dark]{color-scheme:dark;');
+
+    const lightAttributeIndex = css.indexOf('[data-theme=light]');
+    const systemPreferenceIndex = css.indexOf(
+      '@media(prefers-color-scheme:dark)',
+    );
+    const darkAttributeIndex = css.indexOf('[data-theme=dark]');
+
+    expect(lightAttributeIndex).toBeLessThan(systemPreferenceIndex);
+    expect(systemPreferenceIndex).toBeLessThan(darkAttributeIndex);
+    expect(css).not.toContain('@media(prefers-color-scheme:dark){:root{');
+  });
+
+  it('aliases the focus ring color to the primary semantic in both themes', () => {
+    const css = compileScss(`
+      @use 'foundations/color.theme.light' as light;
+      @use 'foundations/color.theme.dark' as dark;
+    `);
+
+    expect(css).toMatch(
+      /:root\{[^}]*--oc-color-theme-focus-ring:var\(--oc-color-theme-primary-normal\)/,
+    );
+    expect(css).toMatch(
+      /\[data-theme=dark\]\{[^}]*--oc-color-theme-focus-ring:var\(--oc-color-theme-primary-normal\)/,
     );
-    expect(css).toContain('[data-theme=light]');
-    expect(css).toContain('@media(prefers-color-scheme:dark)');
-    expect(css).toContain('[data-theme=dark]');
   });
 
   it('emits only light when $oc-color-themes is (light)', () => {
@@ -44,7 +70,8 @@ describe('color theme foundations', () => {
       @use 'foundations/color.theme.dark' as dark;
     `);
 
-    expect(css).toContain('[data-theme=light]');
+    expect(css).toContain(':root{color-scheme:light;');
+    expect(css).toContain('[data-theme=light]{color-scheme:light;');
     expect(css).not.toContain('@media(prefers-color-scheme:dark)');
     expect(css).not.toContain('[data-theme=dark]');
     expect(css).not.toContain(
@@ -61,7 +88,8 @@ describe('color theme foundations', () => {
 
     expect(css).not.toContain('@media(prefers-color-scheme:dark)');
     expect(css).not.toContain('[data-theme=light]');
-    expect(css).toContain('[data-theme=dark]');
+    expect(css).toContain(':root{color-scheme:dark;');
+    expect(css).toContain('[data-theme=dark]{color-scheme:dark;');
     expect(css).toMatch(
       /:root\{[^}]*--oc-color-theme-background-normal-normal:var\(--oc-color-global-coolNeutral-15\)/,
     );
@@ -75,8 +103,9 @@ describe('color theme foundations', () => {
     `);
 
     expect(css).not.toContain('@media(prefers-color-scheme:dark)');
-    expect(css).toContain('[data-theme=light]');
-    expect(css).toContain('[data-theme=dark]');
+    expect(css).toContain(':root{color-scheme:light;');
+    expect(css).toContain('[data-theme=light]{color-scheme:light;');
+    expect(css).toContain('[data-theme=dark]{color-scheme:dark;');
   });
 
   it('throws when $oc-color-themes is empty', () => {

package/src/scss/foundations/color.theme.dark.scss

@@ -3,10 +3,13 @@
 @use '../mixins/color' as *;
 
 @mixin color-theme-dark {
+  color-scheme: dark;
+
   --oc-color-theme-static-white: var(--oc-color-global-common-100);
   --oc-color-theme-static-black: var(--oc-color-global-common-0);
   --oc-color-theme-static-transparent: var(--oc-color-global-common-transparent);
   --oc-color-theme-primary-normal: var(--oc-color-global-redOrange-60);
+  --oc-color-theme-focus-ring: var(--oc-color-theme-primary-normal);
   --oc-color-theme-label-strong: var(--oc-color-global-common-100);
   --oc-color-theme-label-normal: var(--oc-color-global-coolNeutral-99);
   --oc-color-theme-label-neutral: #{oc-alpha(coolNeutral-90, 88)};
@@ -67,7 +70,7 @@
       @include color-theme-dark;
     }
   } @else if config.$oc-color-system-preference {
-    :root {
+    :root:where(:not([data-theme='light'])) {
       @media (prefers-color-scheme: dark) {
         @include color-theme-dark;
       }

package/src/scss/foundations/color.theme.light.scss

@@ -3,10 +3,13 @@
 @use '../mixins/color' as *;
 
 @mixin color-theme-light {
+  color-scheme: light;
+
   --oc-color-theme-static-white: var(--oc-color-global-common-100);
   --oc-color-theme-static-black: var(--oc-color-global-common-0);
   --oc-color-theme-static-transparent: var(--oc-color-global-common-transparent);
   --oc-color-theme-primary-normal: var(--oc-color-global-redOrange-50);
+  --oc-color-theme-focus-ring: var(--oc-color-theme-primary-normal);
   --oc-color-theme-label-strong: var(--oc-color-global-common-0);
   --oc-color-theme-label-normal: var(--oc-color-global-coolNeutral-10);
   --oc-color-theme-label-neutral: #{oc-alpha(coolNeutral-22, 88)};

package/src/scss/foundations/focus.scss

@@ -0,0 +1,4 @@
+:root {
+  --oc-focus-ring-width: 2px;
+  --oc-focus-ring-offset: 2px;
+}

package/src/scss/foundations/focus.test.ts

@@ -0,0 +1,48 @@
+import { compileString } from 'sass';
+import { describe, expect, it } from 'vitest';
+
+describe('focus foundation', () => {
+  const compileFocus = () =>
+    compileString("@use 'foundations/focus' as *;", {
+      loadPaths: ['src/scss'],
+    });
+
+  it('exposes the focus ring size tokens', () => {
+    const result = compileFocus();
+
+    expect(result.css).toContain('--oc-focus-ring-width: 2px;');
+    expect(result.css).toContain('--oc-focus-ring-offset: 2px;');
+  });
+
+  // Protects the documented Full Foundation Rebuild composition
+  // (docs/responsive-foundation-profile.md): replacing foundations.css with
+  // the SCSS-source imports must still emit the focus ring tokens, or the
+  // reset-layer outline declarations become invalid at computed-value time.
+  it('keeps focus tokens in the full foundation rebuild composition', () => {
+    const result = compileString(
+      `
+      @use 'foundations/responsive.config' with (
+        $oc-responsive-mode: static,
+        $oc-responsive-static-stop: md
+      );
+      @use 'foundations/color.global' as *;
+      @use 'foundations/color.theme.light' as *;
+      @use 'foundations/color.theme.dark' as *;
+      @use 'foundations/breakpoint' as *;
+      @use 'foundations/typo' as *;
+      @use 'foundations/space' as *;
+      @use 'foundations/atomic' as *;
+      @use 'foundations/focus' as *;
+      @use 'foundations/motion' as *;
+      @use 'foundations/zindex' as *;
+      `,
+      { loadPaths: ['src/scss'] },
+    );
+
+    expect(result.css).toContain('--oc-focus-ring-width: 2px;');
+    expect(result.css).toContain('--oc-focus-ring-offset: 2px;');
+    expect(result.css).toContain(
+      '--oc-color-theme-focus-ring: var(--oc-color-theme-primary-normal);',
+    );
+  });
+});

package/src/scss/foundations/reset.scss

@@ -1,3 +1,5 @@
+@use '../mixins/focus' as *;
+
 /* Box sizing rules */
 *,
 *::before,
@@ -106,10 +108,13 @@ button {
   appearance: none;
 }
 
-button {
-  &:focus-visible {
-    outline: none;
-  }
+/* Centralized keyboard focus ring. :where() keeps specificity at 0 so any
+   component-level outline declaration overrides it. Text-entry controls
+   (input/textarea/select) are excluded: they match :focus-visible on pointer
+   focus per spec, and the Field family owns focus presentation via its
+   :focus-within stroke. */
+:where(button, a[href], summary, [tabindex]):where(:focus-visible) {
+  @include oc-focus-ring;
 }
 
 textarea,

package/src/scss/foundations/reset.test.ts

@@ -0,0 +1,32 @@
+import { compileString } from 'sass';
+import { describe, expect, it } from 'vitest';
+
+describe('reset foundation', () => {
+  const compileReset = () =>
+    compileString("@use 'foundations/reset';", {
+      loadPaths: ['src/scss'],
+    });
+
+  it('provides the centralized keyboard focus ring for focusable elements', () => {
+    const result = compileReset();
+
+    // Both halves stay inside :where() so the whole selector is specificity 0
+    // and any local outline declaration wins.
+    expect(result.css).toContain(
+      ':where(button, a[href], summary, [tabindex]):where(:focus-visible)',
+    );
+    expect(result.css).toContain(
+      'outline: var(--oc-focus-ring-width) solid var(--oc-color-theme-focus-ring);',
+    );
+    expect(result.css).toContain(
+      'outline-offset: var(--oc-focus-ring-offset);',
+    );
+  });
+
+  it('no longer suppresses the native button focus outline', () => {
+    const result = compileReset();
+    const normalized = result.css.replace(/\s+/g, '');
+
+    expect(normalized).not.toContain('button:focus-visible{outline:none');
+  });
+});

package/src/scss/index.scss

@@ -5,6 +5,7 @@
 @forward './foundations/typo';
 @forward './foundations/space';
 @forward './foundations/atomic';
+@forward './foundations/focus';
 @forward './foundations/motion';
 @forward './foundations/zindex';
 @forward './foundations/reset';
@@ -14,6 +15,7 @@
 @forward './mixins/color';
 @forward './mixins/typo';
 @forward './mixins/element';
+@forward './mixins/focus';
 @forward './mixins/radius';
 @forward './mixins/motion';
 @forward './spring';

package/src/scss/mixins/_focus.scss

@@ -0,0 +1,11 @@
+/**
+ * Keyboard focus ring contract. The ring is drawn with `outline` so it
+ * follows the host element's own border-radius, stays out of layout, and
+ * survives forced-colors mode. The Interaction primitive keeps owning the
+ * surface tint; it cannot carry the ring because its element opacity (the
+ * tint mechanism) would multiply into anything painted in its subtree.
+ */
+@mixin oc-focus-ring($color: var(--oc-color-theme-focus-ring), $width: var(--oc-focus-ring-width), $offset: var(--oc-focus-ring-offset)) {
+  outline: $width solid $color;
+  outline-offset: $offset;
+}

package/src/scss/mixins/_focus.test.ts

@@ -0,0 +1,58 @@
+import { compileString } from 'sass';
+import { describe, expect, it } from 'vitest';
+
+describe('focus utilities', () => {
+  const compileFocus = (scss: string) =>
+    compileString(
+      `
+      @use 'mixins/focus' as *;
+
+      ${scss}
+      `,
+      {
+        loadPaths: ['src/scss'],
+      },
+    );
+
+  it('emits the token-based focus ring by default', () => {
+    const result = compileFocus(`
+      .target {
+        &:focus-visible {
+          @include oc-focus-ring;
+        }
+      }
+    `);
+
+    expect(result.css).toContain(
+      'outline: var(--oc-focus-ring-width) solid var(--oc-color-theme-focus-ring);',
+    );
+    expect(result.css).toContain(
+      'outline-offset: var(--oc-focus-ring-offset);',
+    );
+  });
+
+  it('accepts a custom color', () => {
+    const result = compileFocus(`
+      .target {
+        @include oc-focus-ring($color: var(--custom-ring-color));
+      }
+    `);
+
+    expect(result.css).toContain(
+      'outline: var(--oc-focus-ring-width) solid var(--custom-ring-color);',
+    );
+  });
+
+  it('accepts custom width and offset', () => {
+    const result = compileFocus(`
+      .target {
+        @include oc-focus-ring($width: 3px, $offset: 1px);
+      }
+    `);
+
+    expect(result.css).toContain(
+      'outline: 3px solid var(--oc-color-theme-focus-ring);',
+    );
+    expect(result.css).toContain('outline-offset: 1px;');
+  });
+});