### Initial Project Setup

Source: https://github.com/kufu/smarthr-design-system/blob/main/_autodocs/development-guide.md

Clone the repository, install dependencies, and start the development server.

```bash
git clone https://github.com/kufu/smarthr-design-system.git
cd smarthr-design-system

pnpm install

pnpm dev
```

--------------------------------

### Install Git Hooks

Source: https://github.com/kufu/smarthr-design-system/blob/main/_autodocs/development-guide.md

Enables pre-commit hooks managed by husky.

```bash
husky install
```

--------------------------------

### Start Local Development Server

Source: https://github.com/kufu/smarthr-design-system/blob/main/_autodocs/development-guide.md

Use this command to start the local development server with Hot Module Replacement (HMR). The server typically runs on http://localhost:3000.

```bash
pnpm dev
```

--------------------------------

### Example Article Frontmatter

Source: https://github.com/kufu/smarthr-design-system/blob/main/_autodocs/configuration.md

Illustrates a complete frontmatter block for an article, including title, description, and order.

```mdx
---
title: Button Component
description: Guide to using the Button component with examples and best practices
order: 1
deprecated: false
---

# Button Component Content...
```

--------------------------------

### Construct URLs with URL Object

Source: https://github.com/kufu/smarthr-design-system/blob/main/_autodocs/configuration.md

Examples demonstrating how to construct various URLs using the URL constructor with predefined constants.

```typescript
// Fetch pattern code from GitHub
const patternUrl = new URL(`${patternName}/${patternName}.tsx`, PATTERNS_GITHUB_RAW);

// Link to specific SmartHR UI version on GitHub
const uiSourceUrl = new URL(`smarthr-ui-v${version}/${filePath}`, SHRUI_GITHUB_RAW);

// Storybook story URL
const storybookUrl = new URL(`?path=/story/${storyId}`, storybookBaseUrl);

// Chromatic iframe (using Storybook version from cache)
const iframeUrl = new URL('/iframe.html', `https://${commitHash}--${SHRUI_CHROMATIC_ID}.chromatic.com/`);
```

--------------------------------

### Example 3: F-Pattern with Pagination Considerations

Source: https://github.com/kufu/smarthr-design-system/blob/main/plugins/smarthr-design-system/skills/design-pattern-guidelines/patterns/visual-guidance.mdx

Shows an F-pattern layout for object lists, highlighting potential issues with pagination visibility and primary action placement. This example emphasizes how layout can affect user flow and element discoverability.

```astro
<Cluster gap={{ row: 0, column: 1 }}>
  <DoAndDont type="do" width="calc(50% - 8px)">
    <Image slot="img" src={Sample3Do} alt="Do" />
    <Text slot="label">
      <a href="#h4-0">F型の視線移動</a>を考慮した配置になっている
    </Text>
  </DoAndDont>

  <DoAndDont type="dont" width="calc(50% - 8px)">
    <Image slot="img" src={Sample3Dont} alt="Dont" />
    <Text slot="label">
      オブジェクトの一覧画面から<a href="#h4-0">F型の視線移動</a>を期待するレイアウトだが、視線の流れが途切れやすい配置になっている
      <List>
        <li>検索フォームがなく空白であるため、視線を横に移動する起点がなく<a href="/products/components/pagination/">Pagination</a>が見逃される可能性がある</li>
        <li>［オブジェクトを追加］は一覧画面における主要なアクションにはなりえないため、目立たせる目的で使われている結果、このボタンで視線の流れが途切れる可能性がある</li>
        <li>オブジェクトの操作が行の途中に設置されており、項目2に視線が流れない可能性がある</li>
      </List>
    </Text>
  </DoAndDont>
</Cluster>
```

--------------------------------

### Add Editable Code Example

Source: https://github.com/kufu/smarthr-design-system/blob/main/_autodocs/development-guide.md

Create an editable code example with the CodeBlock component. Provide the code, language, and scope for interactive elements like Buttons.

```mdx
<CodeBlock
  code={`const MyButton = () => (
    <Button>Click me</Button>
  );`}
  language="tsx"
  editable
  scope={{ Button }}
/>
```

--------------------------------

### Install Plugin for Claude Code

Source: https://github.com/kufu/smarthr-design-system/blob/main/plugins/smarthr-design-system/README.md

Use these commands to add and install the smarthr-design-system plugin for Claude Code.

```sh
/plugin marketplace add kufu/smarthr-design-system
/plugin install smarthr-design-system@smarthr-design-system
```

--------------------------------

### Troubleshoot Dependency Conflicts

Source: https://github.com/kufu/smarthr-design-system/blob/main/_autodocs/development-guide.md

Commands to check for peer dependency warnings and update the lock file to resolve installation issues.

```bash
# Check for peer dependency warnings
pnpm install --strict-peer-dependencies

# Update lock file
pnpm install --frozen-lockfile=false
```

--------------------------------

### Accessibility Guidelines Example

Source: https://github.com/kufu/smarthr-design-system/blob/main/_autodocs/development-guide.md

Include an accessibility section to outline important guidelines for users. This ensures inclusivity and usability.

```mdx
## Accessibility

- ARIA labels required for icon-only buttons
- Color alone must not convey information
- Keyboard navigation must work
- Screen readers must announce purpose
```

--------------------------------

### DefinitionList - Basic Usage

Source: https://github.com/kufu/smarthr-design-system/blob/main/plugins/smarthr-design-system/skills/component-guidelines/components/DefinitionList.md

A basic example of using DefinitionList with DefinitionListItem to display a single term and its content.

```jsx
<DefinitionList>
  <DefinitionListItem term="項目1">内容1</DefinitionListItem>
</DefinitionList>
```

--------------------------------

### Navigation Link Example

Source: https://github.com/kufu/smarthr-design-system/blob/main/_autodocs/development-guide.md

Use this format for linking to related articles within the site. URLs are relative to the site root.

```mdx
[Related Article](/products/design-patterns/button-states)
```

--------------------------------

### Chip Component Example

Source: https://github.com/kufu/smarthr-design-system/blob/main/src/content/articles/products/components/chip/index.mdx

Demonstrates the basic usage of the Chip component. This component is suitable for displaying text that functions as tags or categories.

```astro
import ComponentStory from '@/components/article/ComponentStory.astro'
import ComponentPropsTable from '@/components/article/ComponentPropsTable.astro'
import Checklist from '@/components/article/Checklist/Checklist.astro'
import { Chip, Cluster, FaCircleXmarkIcon, Stack, UnstyledButton } from 'smarthr-ui'

<ComponentStory name="Chip" />
```

--------------------------------

### Dialog Trigger - OK Example

Source: https://github.com/kufu/smarthr-design-system/blob/main/plugins/smarthr-design-system/skills/component-guidelines/components/Dialog.md

Demonstrates the correct usage of DialogTrigger, ensuring its child is a button element.

```jsx
<DialogTrigger>
  <XxxButton />
</DialogTrigger>
```

--------------------------------

### Button Component Example

Source: https://github.com/kufu/smarthr-design-system/blob/main/src/content/articles/operational-guideline/page-template/style-template.mdx

Demonstrates the usage of the Button component with different variants. Use one code snippet per component.

```tsx
<Button variant="primary">Button</Button>
<Button>Button</Button>
<Button variant="danger">Button</Button>
<Button variant="text">Button</Button>
<Button variant="skeleton">Button</Button>
```

--------------------------------

### FloatArea Layout - Do Example

Source: https://github.com/kufu/smarthr-design-system/blob/main/src/content/articles/products/components/float-area/index.mdx

Demonstrates the correct placement of FloatArea, ensuring it visually indicates its target area by overlapping only the relevant column.

```jsx
<DoAndDont type="do">
  <Image slot="img" src={FloatAreaLayoutDo} alt="Do" />
  <Text slot="label">FloatAreaが右側のカラムだけに重なっているため、右側のカラムだけがFloatAreaの対象の領域であることがわかる</Text>
</DoAndDont>
```

--------------------------------

### Preview Production Build Locally

Source: https://github.com/kufu/smarthr-design-system/blob/main/_autodocs/development-guide.md

Serves the production build ('dist/') locally for preview.

```bash
pnpm preview
```

--------------------------------

### Detailed Operation Guide Link Pattern

Source: https://github.com/kufu/smarthr-design-system/blob/main/src/content/articles/products/contents/ui-text/help-link.mdx

Use this pattern to link to detailed instructions for a specific operation. It starts with the operation name and 'の詳しい操作方法は、' followed by the help page title.

```text
{hoge}の詳しい操作方法は、{ヘルプページタイトル}<OpenInNewTabIcon visuallyHiddenText="新規ウィンドウ" />を参照してください。
```

--------------------------------

### Build Static Site for Production

Source: https://github.com/kufu/smarthr-design-system/blob/main/_autodocs/development-guide.md

Builds the static site for production, creating a 'dist/' directory.

```bash
pnpm build
```

--------------------------------

### Example 2: Z-Pattern Visual Guidance

Source: https://github.com/kufu/smarthr-design-system/blob/main/plugins/smarthr-design-system/skills/design-pattern-guidelines/patterns/visual-guidance.mdx

Illustrates a Z-pattern layout for guiding the eye through key information and actions. This pattern is effective for interfaces where a clear path is needed to direct user attention.

```astro
<Cluster gap={{ row: 0, column: 1 }}>
  <DoAndDont type="do" width="calc(50% - 8px)">
    <Image slot="img" src={Sample2Do} alt="Do" />
    <Text slot="label">
      <a href="#h4-1">Z型の視線移動</a>を考慮した配置になっており、主要な情報とアクションが見逃されにくい
    </Text>
  </DoAndDont>

  <DoAndDont type="dont" width="calc(50% - 8px)">
    <Image slot="img" src={Sample2Dont} alt="Dont" />
    <Text slot="label">
      <a href="/products/components/float-area/">FloatArea</a>の採用から<a href="#h4-1">Z型の視線移動</a>を期待するレイアウトだが、［操作ボタン1］［目的となるボタン］が「Z」の視線上に配置されていない
    </Text>
  </DoAndDont>
</Cluster>
```

--------------------------------

### Retrieve and Filter Astro Articles

Source: https://github.com/kufu/smarthr-design-system/blob/main/_autodocs/api-reference-lib.md

Use this snippet to fetch articles from an Astro content collection based on a base path and optional exclusion patterns. It demonstrates how to get all component pages and how to exclude specific pages, such as deprecated ones. The example also shows how to iterate through the retrieved entries and render their content.

```typescript
import { getSubPageCollection } from '@/lib/getSubPageCollection';

// Get all component pages
const components = await getSubPageCollection('products/components');

// Get all component pages except deprecated ones
const activeComponents = await getSubPageCollection(
  'products/components',
  ['deprecated']  // Excludes any page with 'deprecated' in its path
);

// Iterate and render
for (const entry of components) {
  const { title, order } = entry.data;
  const { Content } = await entry.render();
  console.log(`${order}: ${title}`);
}
```

--------------------------------

### Create New Article Directory and File

Source: https://github.com/kufu/smarthr-design-system/blob/main/_autodocs/development-guide.md

Use these bash commands to create the necessary directory structure and the index.mdx file for a new article.

```bash
mkdir -p src/content/articles/products/my-section/my-page
touch src/content/articles/products/my-section/my-page/index.mdx
```

--------------------------------

### Grammar Simplification Example

Source: https://github.com/kufu/smarthr-design-system/blob/main/src/content/articles/accessibility/insight/yasashii-nihongo/method.mdx

Simplifies complex grammar to intermediate or lower levels. This example replaces the N1 grammar 'いずれ' with N5 grammar '〜か〜'.

```Japanese
下記のいずれかに該当する扶養家族はいますか？
```

```Japanese
あなたの　扶養になっている　家族で　次の　1か 2の人は　いますか？
```

--------------------------------

### Create Component Checklist File

Source: https://github.com/kufu/smarthr-design-system/blob/main/_autodocs/development-guide.md

Use bash to create a `checklist.yaml` file within a component's directory to define its checklist items.

```bash
touch src/content/articles/products/components/button/checklist.yaml
```

--------------------------------

### Coverage Baseline JSON Example

Source: https://github.com/kufu/smarthr-design-system/blob/main/scripts/generate-skills/README.md

An example structure for `coverage-baseline.json`, used to list known violations in coverage checks. Refer to the README for operational details.

```json
{
  "$comment": "coverage チェックの既知違反リスト。運用方法は scripts/generate-skills/README.md の「coverage-baseline.json の運用」を参照。",
  "newComponents": ["Balloon"],
  "orphanDirs": [],
  "missingDescriptions": [],
  "unknownRelatedNames": []
}
```

--------------------------------

### Example 1: F-Pattern Visual Guidance

Source: https://github.com/kufu/smarthr-design-system/blob/main/plugins/smarthr-design-system/skills/design-pattern-guidelines/patterns/visual-guidance.mdx

Demonstrates an F-pattern layout for optimal reading flow. Use this when content is primarily text-based and requires a predictable reading order.

```astro
<Cluster gap={{ row: 0, column: 1 }}>
  <DoAndDont type="do" width="calc(50% - 8px)">
    <Image slot="img" src={Sample1Do} alt="Do" />
    <Text slot="label"><a href="#h4-0">F型の視線移動</a>を考慮した配置になっている</Text>
  </DoAndDont>
  <DoAndDont type="dont" width="calc(50% - 8px)">
    <Image slot="img" src={Sample1Dont} alt="Dont" />
    <Text slot="label">
      <a href="#h4-0">F型の視線移動</a>を考慮した配置になっていない
      <List>
        <li>見出しがフォーム領域（<a href="/products/components/base/">Base</a>）に対して左側に配置されていない</li>
        <li>フォームが入力してほしい順序に上から下に並んでいない</li>
        <li>見出しの直後に［目的となるボタン］が配置されており、「フォームの入力後にボタンを押す」という視線の流れにならない</li>
      </List>
    </Text>
  </DoAndDont>
</Cluster>
```

--------------------------------

### Select Component - Bad Implementation Example

Source: https://github.com/kufu/smarthr-design-system/blob/main/src/content/articles/products/components/select/index.mdx

An example of an incorrect implementation where the label is not associated with the Select component. This can lead to accessibility issues, as screen readers may not convey the selection's purpose.

```tsx
// ❌ ラベルとSelectが関連付けられていない
<Stack gap={0.5}>
  <Text styleType="blockTitle">都道府県</Text>
  <Select
    name="prefecture"
    options={[
      { label: '北海道', value: 'hokkaido' },
      { label: '青森県', value: 'aomori' },
    ]}
  />
</Stack>
```

--------------------------------

### Example Checklist YAML

Source: https://github.com/kufu/smarthr-design-system/blob/main/_autodocs/configuration.md

Illustrates a complete checklist file with multiple items, demonstrating the use of severity levels, text, source sections, and sub-items.

```yaml
items:
  - severity: must
    text: Always provide a clear, action-oriented label
    source_section: Usage > Best Practices
    note: Users must understand what happens when they click

  - severity: should
    text: Limit labels to 2-3 words when possible
    source_section: Usage > Best Practices
    sub_items:
      - Keep text concise for mobile viewports
      - Avoid abbreviations that require explanation

  - severity: avoid
    text: Do not use ALL CAPS in button labels
    source_section: Usage > Accessibility
    note: Causes reading speed reduction for screen reader users
```

--------------------------------

### Generate Component Preview Thumbnails

Source: https://github.com/kufu/smarthr-design-system/blob/main/_autodocs/development-guide.md

Creates thumbnail images for component previews.

```bash
pnpm generate:thumbnails
```

--------------------------------

### Product Meta Tags for Head Section

Source: https://github.com/kufu/smarthr-design-system/blob/main/src/content/articles/basics/meta/index.mdx

This code example includes basic meta tags for product pages where OGP information might not be necessary. It omits OGP settings, assuming these pages may require login.

```html
<link rel="icon" href="/favicon.ico">
<link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png">
<link rel="manifest" href="/manifest.webmanifest">
<meta name="apple-mobile-web-app-title" content="SmartHR">
<meta name="application-name" content="SmartHR">

```

--------------------------------

### Do/Don't: Avoid Multi-Column Layouts on Mobile

Source: https://github.com/kufu/smarthr-design-system/blob/main/plugins/smarthr-design-system/skills/design-pattern-guidelines/patterns/page-layout.mdx

Demonstrates how to avoid multi-column layouts on mobile devices to maintain readability. The 'Don't' example shows a difficult-to-read multi-column layout, while the 'Do' example illustrates a vertically stacked layout for better comprehension.

```tsx
<Sidebar>
  <Base padding={1} style={{ width: '1rem' }}>
    <Stack gap={0.5}>
      <Heading type="blockTitle">複数カラムのレイアウトを避ける</Heading>
      <p>折り返しの多すぎるコンテンツの理解は難しいです。</p>
    </Stack>
  </Base>
  <Base padding={1} style={{ flexGrow: 1 }}>
    <Stack>
      <p>構造関係の理解も難しくなります。</p>
      <p>DOMはそのままに、適切な幅で折り返し垂直方向に積み上げるなど代替レイアウトを検討してください。</p>
    </Stack>
  </Base>
</Sidebar>
```

```tsx
<Stack>
  <Base padding={1}>
    <Stack gap={0.5}>
      <Heading type="blockTitle">複数カラムのレイアウトを避ける</Heading>
      <p>折り返しの多すぎるコンテンツの理解は難しいです。</p>
    </Stack>
  </Base>
  <Base padding={1}>
    <Stack>
      <p>構造関係の理解も難しくなります。</p>
      <p>DOMはそのままに、適切な幅で折り返し垂直方向に積み上げるなど代替レイアウトを検討してください。</p>
    </Stack>
  </Base>
</Stack>
```

--------------------------------

### Dialog Trigger - NG Example

Source: https://github.com/kufu/smarthr-design-system/blob/main/plugins/smarthr-design-system/skills/component-guidelines/components/Dialog.md

Illustrates an incorrect usage of DialogTrigger where the child is not solely a button element.

```jsx
// Triggerの子はbutton要素のみである必要がある
<DialogTrigger>
  <Button />
  <Any />
</DialogTrigger>
```

--------------------------------

### Shadow Sample Component Usage

Source: https://github.com/kufu/smarthr-design-system/blob/main/src/content/articles/products/design-tokens/shadow/index.mdx

Demonstrates the usage of the ShadowSample component with different depth values to visualize various shadow effects.

```javascript
<ComponentPreview>
  <ShadowSample depth={0} />
  <ShadowSample depth={1} />
  <ShadowSample depth={2} />
  <ShadowSample depth={3} />
  <ShadowSample depth={4} />
</ComponentPreview>
```

--------------------------------

### モバイル判定にuseEnvironmentフックを使用

Source: https://github.com/kufu/smarthr-design-system/blob/main/src/content/articles/products/design-patterns/mobile-friendly-layout/index.mdx

モバイル環境かどうかを判定するために`useEnvironment`フックを使用します。これにより、各プロダクトでユーザーエージェントの判定を実装する必要がなくなります。モバイル向けの値とデスクトップ向けの値で条件分岐を行う際に利用します。

```tsx
import { useEnvironment } from 'smarthr-ui'

export const YourComponent = () => {
  const { mobile } = useEnvironment()

  return (
    <SomeComponent 
      someProp={mobile ? モバイル向けの値 : デスクトップ向けの値}
    >
      {/* コンテンツ */}
    </SomeComponent>
  )
}
```

--------------------------------

### Component Props Table Example

Source: https://github.com/kufu/smarthr-design-system/blob/main/_autodocs/development-guide.md

Document component properties using a markdown table. Include prop name, type, requirement, and a description.

```mdx
| Prop | Type | Required | Description |
|------|------|----------|-------------|
| label | string | Yes | Button text |
| variant | 'primary' \| 'secondary' | No | Button style |
```

--------------------------------

### Troubleshoot Cache Issues

Source: https://github.com/kufu/smarthr-design-system/blob/main/_autodocs/development-guide.md

Commands to clear Astro cache, prune pnpm store, and perform a fresh installation of dependencies.

```bash
# Clear Astro cache
rm -rf .astro

# Clear pnpm cache (careful!)
pnpm store prune

# Fresh install
rm -rf node_modules pnpm-lock.yaml
pnpm install
```

--------------------------------

### MDX File Structure with JSX

Source: https://github.com/kufu/smarthr-design-system/blob/main/_autodocs/astro-integration.md

Demonstrates how to structure an MDX file, including frontmatter, Markdown content, and embedded JSX components like Buttons.

```mdx
---
title: Button Component
description: Usage and guidelines
---

# {frontmatter.title}

Here's a button:

import Button from 'smarthr-ui';
import CodeBlock from '@/components/CodeBlock';

<CodeBlock code="<Button>Click me</Button>" editable language="tsx" />

## Best Practices

- Always provide accessible labels...
```