feat: docsのui/をBlocks / Examplesの2分類にし、作例を/ui/examples/へ統合する

.claude/commands/docs-update.md

@@ -27,8 +27,7 @@ argument-hint: "[対象ファイル/ディレクトリ... | root]"
 | D | `property-class/` | プロパティクラス | `lism-css` の config・SCSS |
 | E | `tokens/` | デザイントークン | `lism-css` の config・SCSS |
 | F | `ui/` 直下 | `@lism-css/ui` コンポーネント（Blocks） | `lism-ui` のソース |
-| G | `ui/block-examples/` | パッケージ外の b-- 部品作例（Block Examples） | `lism-css` のコンポーネント |
-| G' | `ui/components/` | 独自 CSS なしの実装例（Components） | `lism-css` のコンポーネント |
+| G | `ui/examples/` | パッケージ外の部品・技法の実装例（Examples） | `lism-css` のコンポーネント |
 | H | `customize/` とルート直下 | 概要・導入・カスタマイズガイド | `package.json`、ビルド設定、ソース全般 |
 
 3件以下のグループは隣接グループと統合し、多いグループ（H 等）は分割してよい。

apps/site/src/config/redirects.ts

@@ -91,33 +91,33 @@ export const astroRedirects: AstroRedirects = {
   // purge -> customize/purge 移動（Customize セクション化に伴う統合）
   '/docs/purge/': '/docs/customize/purge/',
   '/en/docs/purge/': '/en/docs/customize/purge/',
-  // Chat をパッケージから削除し、Block Examples の作例ページへ転換（#557）
-  '/ui/chat/': '/ui/block-examples/chat/',
-  '/en/ui/chat/': '/en/ui/block-examples/chat/',
-  // 公開実績のある旧ui/examples/*だけをui/components/*へリダイレクトする（#557）
-  '/ui/examples/banner/': '/ui/components/banner/',
-  '/ui/examples/breadcrumb/': '/ui/components/breadcrumb/',
-  '/ui/examples/card/': '/ui/components/card/',
-  '/ui/examples/dividerlabel/': '/ui/components/dividerlabel/',
-  '/ui/examples/reel/': '/ui/components/reel/',
-  '/en/ui/examples/banner/': '/en/ui/components/banner/',
-  '/en/ui/examples/breadcrumb/': '/en/ui/components/breadcrumb/',
-  '/en/ui/examples/card/': '/en/ui/components/card/',
-  '/en/ui/examples/dividerlabel/': '/en/ui/components/dividerlabel/',
-  '/en/ui/examples/reel/': '/en/ui/components/reel/',
-  // Steps は MDX を削除し、Timeline は MDX を draft 化して本番非公開にしたため、作例のある patterns へ誘導する。ui/examples/*からの連鎖も避ける
+  // ui/の作例ページは/ui/examples/{slug}/。公開実績のある旧URLだけを登録する
+  // 公開中の作例と同じURL（/ui/examples/card/等）は登録しない。静的ルートのリダイレクトが[...slug]の実ページより優先される
+  '/ui/chat/': '/ui/examples/chat/',
+  '/ui/block-examples/chat/': '/ui/examples/chat/',
+  '/ui/components/banner/': '/ui/examples/banner/',
+  '/ui/components/breadcrumb/': '/ui/examples/breadcrumb/',
+  '/ui/components/card/': '/ui/examples/card/',
+  '/ui/components/dividerlabel/': '/ui/examples/dividerlabel/',
+  '/ui/components/reel/': '/ui/examples/reel/',
+  '/en/ui/chat/': '/en/ui/examples/chat/',
+  '/en/ui/block-examples/chat/': '/en/ui/examples/chat/',
+  '/en/ui/components/banner/': '/en/ui/examples/banner/',
+  '/en/ui/components/breadcrumb/': '/en/ui/examples/breadcrumb/',
+  '/en/ui/components/card/': '/en/ui/examples/card/',
+  '/en/ui/components/dividerlabel/': '/en/ui/examples/dividerlabel/',
+  '/en/ui/components/reel/': '/en/ui/examples/reel/',
+  // Steps・Timeline・FAQ・Heroの作例はpatternsにある。旧URLから直接リダイレクトし、連鎖させない
   '/ui/components/steps/': '/patterns/process/',
   '/ui/examples/steps/': '/patterns/process/',
   '/ui/block-examples/timeline/': '/patterns/process/',
-  '/en/ui/components/steps/': '/en/patterns/process/',
-  '/en/ui/examples/steps/': '/en/patterns/process/',
-  '/en/ui/block-examples/timeline/': '/en/patterns/process/',
-  // FAQ/Hero は patterns のカテゴリページへ直接リダイレクトし、ui/examples/*からの連鎖を避ける（#566）
   '/ui/components/faq/': '/patterns/faq/',
-  // Hero は MDX を draft 化して本番非公開にしたため、作例のある patterns へ誘導する
   '/ui/components/hero/': '/patterns/hero/',
   '/ui/examples/faq/': '/patterns/faq/',
   '/ui/examples/hero/': '/patterns/hero/',
+  '/en/ui/components/steps/': '/en/patterns/process/',
+  '/en/ui/examples/steps/': '/en/patterns/process/',
+  '/en/ui/block-examples/timeline/': '/en/patterns/process/',
   '/en/ui/components/faq/': '/en/patterns/faq/',
   '/en/ui/components/hero/': '/en/patterns/hero/',
   '/en/ui/examples/faq/': '/en/patterns/faq/',

apps/site/src/config/sidebar.ts

@@ -212,12 +212,8 @@ const uiSidebar: SidebarSection[] = [
     dir: 'ui', // content/ja/ui/ 直下のMDXを自動取得（パッケージ提供のUI）
   },
   {
-    label: 'Block Examples',
-    dir: 'ui/block-examples', // CSSをコピーして導入するb--部品の作例（#557）
-  },
-  {
-    label: 'Components',
-    dir: 'ui/components', // 独自CSSなしで組み立てる実装例（#557）
+    label: 'Examples',
+    dir: 'ui/examples', // パッケージ外の部品・技法の実装例
   },
 ];
 

apps/site/src/content/en/changelog.mdx

@@ -181,7 +181,7 @@ Requires `lism-css` v0.27.0 or later.
 - Removed `flow="s"` from Details.Content. To retain the previous spacing, set `.b--details_content { --flow--base: var(--flow--s) }` (#559).
 - Added Tabs keyboard navigation and React support for `?lism-tab=`. Switched panels from `aria-hidden` to `hidden` and fixed out-of-range `defaultIndex` (#559).
 - Improved Modal accessibility, fixed unintended closing during dragging and state restoration after closing, and limited `setEvent` to `dialog` elements (#563).
-- Removed Chat from the package. Copy the [example CSS](/en/ui/block-examples/chat/) together with its `@layer lism-block` wrapper (#564).
+- Removed Chat from the package. Copy the [example CSS](/en/ui/examples/chat/) together with its `@layer lism-block` wrapper (#564).
 
 <Divider bds="dashed" my="40" />
 

apps/site/src/content/en/ui/components/BalloonBox.mdx → apps/site/src/content/en/ui/examples/BalloonBox.mdx

@@ -9,7 +9,7 @@ import BalloonBox from '@/components/ex/BalloonBox/index.jsx';
 
 Examples of speech-bubble style decorative boxes built with Lism.
 
-If you need a chat-style conversation UI (a sequence of speech bubbles), see the [Chat](/en/ui/block-examples/chat/) example as well.
+If you need a chat-style conversation UI (a sequence of speech bubbles), see the [Chat](/en/ui/examples/chat/) example as well.
 
 
 ## Source Code

apps/site/src/content/en/ui/components/Decorations.mdx → apps/site/src/content/en/ui/examples/Decorations.mdx

@@ -7,7 +7,7 @@ draft: true
 import { Grid, Flex, Decorator, Box, Spacer } from 'lism-css/astro';
 import { DummyText } from '@lism-css/ui/astro/DummyText';
 
-import '../../../ja/ui/components/_opt-in/_decorations.css';
+import '../../../ja/ui/_opt-in/_decorations.css';
 
 Examples of decorative boxes built with Lism.
 

apps/site/src/content/ja/changelog.mdx

@@ -181,7 +181,7 @@ Lism CSSの各バージョンの変更点を記載します。
 - Details.Contentの`flow="s"`を廃止しました。以前の間隔に戻すには`.b--details_content { --flow--base: var(--flow--s) }`を指定してください（#559）。
 - Tabsのキーボード操作とReact版の`?lism-tab=`に対応しました。パネルを`aria-hidden`から`hidden`へ変更し、範囲外の`defaultIndex`による不具合も修正しました（#559）。
 - Modalのアクセシビリティと開閉処理を改善し、ドラッグ時に誤って閉じる問題や、閉じた後の状態復元を修正しました。`setEvent`の対象は`dialog`要素に限定しました（#563）。
-- Chatをパッケージから削除しました。[実装例](/ui/block-examples/chat/)のCSSを`@layer lism-block`ごとコピーしてください（#564）。
+- Chatをパッケージから削除しました。[実装例](/ui/examples/chat/)のCSSを`@layer lism-block`ごとコピーしてください（#564）。
 
 <Divider bds="dashed" my="40" />
 

apps/site/src/content/ja/ui/components/BalloonBox.mdx → apps/site/src/content/ja/ui/examples/BalloonBox.mdx

@@ -9,7 +9,7 @@ import BalloonBox from '@/components/ex/BalloonBox/index.jsx';
 
 ふきだし風装飾ボックスの作成例を紹介します。
 
-チャットの会話風UI（ふきだしの連続表示）が必要な場合は、[Chat](/ui/block-examples/chat/) の実装例も参照してください。
+チャットの会話風UI（ふきだしの連続表示）が必要な場合は、[Chat](/ui/examples/chat/) の実装例も参照してください。
 
 
 ## Source Code

apps/site/src/content/ja/ui/components/Decorations.mdx → apps/site/src/content/ja/ui/examples/Decorations.mdx

@@ -7,7 +7,7 @@ draft: true
 import { Grid, Flex, Decorator, Box, Spacer } from 'lism-css/astro';
 import { DummyText } from '@lism-css/ui/astro/DummyText';
 
-import './_opt-in/_decorations.css';
+import '../_opt-in/_decorations.css';
 
 装飾ボックスの作成例を紹介します。
 

apps/site/src/integrations/docs-md/build-llms-txt.test.ts

@@ -59,9 +59,8 @@ describe('classify', () => {
     expect(classify('skills.mdx')).toBe('Getting Started');
   });
 
-  it('ui/block-examples と ui/components と property-class は Optional', () => {
-    expect(classify('ui/block-examples/Chat.mdx')).toBe('Optional');
-    expect(classify('ui/components/Foo.mdx')).toBe('Optional');
+  it('ui/examples と property-class は Optional', () => {
+    expect(classify('ui/examples/Chat.mdx')).toBe('Optional');
     expect(classify('property-class/color.mdx')).toBe('Optional');
   });
 
@@ -85,8 +84,7 @@ describe('toUrl', () => {
 
   it('ui/ は /en/ 直下（slug は小文字化される）', () => {
     expect(toUrl('ui/Accordion.mdx', 'https://lism-css.com')).toBe('https://lism-css.com/en/ui/accordion.md');
-    expect(toUrl('ui/components/Banner.mdx', 'https://lism-css.com')).toBe('https://lism-css.com/en/ui/components/banner.md');
-    expect(toUrl('ui/block-examples/Chat.mdx', 'https://lism-css.com')).toBe('https://lism-css.com/en/ui/block-examples/chat.md');
+    expect(toUrl('ui/examples/Banner.mdx', 'https://lism-css.com')).toBe('https://lism-css.com/en/ui/examples/banner.md');
   });
 
   it('docs 系の casing は小文字化される（公開 slug と一致させる）', () => {

apps/site/src/integrations/docs-md/build-llms-txt.ts

@@ -4,8 +4,8 @@
  *
  * セクション分類:
  * - Getting Started: トップレベルの overview/installation/changelog/features/mcp/skills
- * - UI Components:   ui/Xxx.mdx（パッケージ提供の Blocks。block-examples / components 配下を除く）
- * - Optional:        ui/block-examples/*, ui/components/*, property-class/*
+ * - UI Components:   ui/Xxx.mdx（パッケージ提供の Blocks。examples 配下を除く）
+ * - Optional:        ui/examples/*, property-class/*
  * - Documentation:   それ以外すべて
  *
  * `_demo/` と `test.mdx`、`draft: true` のファイルは除外する。
@@ -62,9 +62,8 @@ export function parseFrontmatter(content: string): FrontMatter {
 export function classify(rel: string): Section | null {
   if (rel.startsWith('_demo/') || rel === 'test.mdx') return null;
   const slug = rel.replace(/\.mdx$/, '');
-  // ui/ 直下（パッケージ提供の Blocks）以外の作例・実装例は Optional 扱い（#557）
-  if (rel.startsWith('ui/block-examples/')) return 'Optional';
-  if (rel.startsWith('ui/components/')) return 'Optional';
+  // ui/ 直下（パッケージ提供の Blocks）以外の実装例は Optional 扱い
+  if (rel.startsWith('ui/examples/')) return 'Optional';
   if (rel.startsWith('property-class/')) return 'Optional';
   if (rel.startsWith('ui/')) return 'UI Components';
   if (GS_SLUGS.has(slug)) return 'Getting Started';

apps/site/src/integrations/docs-md/build-ui-index-md.test.ts

@@ -15,7 +15,7 @@ async function writeFile(filePath: string, content: string) {
 }
 
 describe('buildUiIndexMd', () => {
-  it('UI index markdown を3分類で生成し、draft と _ 始まりを除外する', async () => {
+  it('UI index markdown を2分類で生成し、draft と _ 始まりを除外する', async () => {
     const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'lism-ui-index-md-'));
     const htmlPath = path.join(tmpDir, 'dist/ui/index.html');
     const outputPath = path.join(tmpDir, 'dist/ui.md');
@@ -51,23 +51,23 @@ description: Button docs
 body`
       );
       await writeFile(
-        path.join(uiContentDir, 'block-examples/Chat.mdx'),
+        path.join(uiContentDir, 'examples/Chat.mdx'),
         `---
 title: Chat
-description: Chat block example
+description: Chat example
 ---
 body`
       );
       await writeFile(
-        path.join(uiContentDir, 'components/Banner.mdx'),
+        path.join(uiContentDir, 'examples/Banner.mdx'),
         `---
 title: Banner
 description: Banner example
 ---
 body`
       );
       await writeFile(
-        path.join(uiContentDir, 'components/Draft.mdx'),
+        path.join(uiContentDir, 'examples/Draft.mdx'),
         `---
 title: Draft
 description: Draft example
@@ -100,16 +100,14 @@ body`
       expect(md).toContain('## Blocks');
       expect(md).toContain('- [Button](https://lism-css.com/ui/button.md): Button docs');
       expect(md).toContain('- [ShapeDivider](https://lism-css.com/ui/shapedivider.md): Shape divider docs');
-      expect(md).toContain('## Block Examples');
-      expect(md).toContain('- [Chat](https://lism-css.com/ui/block-examples/chat.md): Chat block example');
-      expect(md).toContain('## Components');
-      expect(md).toContain('- [Banner](https://lism-css.com/ui/components/banner.md): Banner example');
+      expect(md).toContain('## Examples');
+      expect(md).toContain('- [Chat](https://lism-css.com/ui/examples/chat.md): Chat example');
+      expect(md).toContain('- [Banner](https://lism-css.com/ui/examples/banner.md): Banner example');
       expect(md).not.toContain('Draft');
       expect(md).not.toContain('Hidden');
       expect(md.indexOf('[Button]')).toBeLessThan(md.indexOf('[ShapeDivider]'));
-      // 見出しの並びは Blocks → Block Examples → Components
-      expect(md.indexOf('## Blocks')).toBeLessThan(md.indexOf('## Block Examples'));
-      expect(md.indexOf('## Block Examples')).toBeLessThan(md.indexOf('## Components'));
+      // 見出しの並びは Blocks → Examples
+      expect(md.indexOf('## Blocks')).toBeLessThan(md.indexOf('## Examples'));
     } finally {
       await fs.rm(tmpDir, { recursive: true, force: true });
     }

apps/site/src/integrations/docs-md/build-ui-index-md.ts

@@ -8,7 +8,7 @@
  *
  * - frontmatter (title / description / url) は dist 側 index.html から抽出して同期を保つ
  * - 本文は content/{lang}/ui/ 配下の `.mdx` から組み立てる（`_` 始まり / `draft: true` は除外）
- * - 見出しは Blocks（ui/ 直下）/ Block Examples（ui/block-examples/）/ Components（ui/components/）の3分類
+ * - 見出しは Blocks（ui/ 直下）/ Examples（ui/examples/）の2分類
  * - リンクは個別ページの `.md`（`convert-html-to-md` が生成済み）を指す
  */
 import fs from 'node:fs/promises';
@@ -54,10 +54,9 @@ export async function buildUiIndexMd(opts: {
 
   // _opt-in / _demo など `_` 始まりは公開対象外なので走査時に除外
   const files = await walkMdx(uiContentDir, { skipUnderscore: true });
-  // ui/ 直下（パッケージ提供）/ block-examples/ / components/ の3分類（#557）
+  // ui/ 直下（パッケージ提供）/ examples/ の2分類
   const blocks: Entry[] = [];
-  const blockExamples: Entry[] = [];
-  const components: Entry[] = [];
+  const examples: Entry[] = [];
 
   for (const rel of files) {
     const abs = path.join(uiContentDir, rel);
@@ -76,15 +75,13 @@ export async function buildUiIndexMd(opts: {
       description: fm.description ?? '',
       slug,
     };
-    if (rel.startsWith('block-examples/')) blockExamples.push(entry);
-    else if (rel.startsWith('components/')) components.push(entry);
+    if (rel.startsWith('examples/')) examples.push(entry);
     else blocks.push(entry);
   }
 
   const sortByTitle = (a: Entry, b: Entry) => a.title.localeCompare(b.title);
   blocks.sort(sortByTitle);
-  blockExamples.sort(sortByTitle);
-  components.sort(sortByTitle);
+  examples.sort(sortByTitle);
 
   const lines: string[] = ['---', `title: ${yamlString(meta.title)}`];
   if (meta.description) lines.push(`description: ${yamlString(meta.description)}`);
@@ -100,20 +97,13 @@ export async function buildUiIndexMd(opts: {
     for (const e of blocks) lines.push(formatEntry(e, uiUrlPrefix));
     lines.push('');
   }
-  if (blockExamples.length > 0) {
-    lines.push('## Block Examples', '');
-    for (const e of blockExamples) lines.push(formatEntry(e, uiUrlPrefix));
-    lines.push('');
-  }
-  if (components.length > 0) {
-    lines.push('## Components', '');
-    for (const e of components) lines.push(formatEntry(e, uiUrlPrefix));
+  if (examples.length > 0) {
+    lines.push('## Examples', '');
+    for (const e of examples) lines.push(formatEntry(e, uiUrlPrefix));
     lines.push('');
   }
 
   await fs.mkdir(path.dirname(outputPath), { recursive: true });
   await fs.writeFile(outputPath, lines.join('\n'));
-  logger.info(
-    `generated ${path.basename(outputPath)} (${blocks.length} blocks, ${blockExamples.length} block examples, ${components.length} components)`
-  );
+  logger.info(`generated ${path.basename(outputPath)} (${blocks.length} blocks, ${examples.length} examples)`);
 }