---
import DocLayout from "../layouts/DocLayout.astro";
import Heading from "../components/docs/Heading.astro";
import ComponentSection from "../components/docs/ComponentSection.astro";
import CodeBlock from "../components/docs/CodeBlock.astro";
---

<DocLayout
  title="Contributing"
  description="Learn how to contribute to Kumo, including workflow for adding components, blocks and layouts."
>
  <!-- Repository Contribution Workflow -->
  <ComponentSection>
    <Heading level={2}>Repository Contribution Workflow</Heading>
    <p class="mb-4 text-kumo-strong">
      Useful commands for developing Kumo (run from repository root):
    </p>
    <ul class="list-inside list-disc space-y-2 text-kumo-default">
      <li>
        Build everything once: <code class="rounded bg-kumo-control px-1 py-0.5 text-sm"
          >pnpm i; pnpm build</code
        >
      </li>
      <li>
        Use watch mode while developing: <code class="rounded bg-kumo-control px-1 py-0.5 text-sm"
          >pnpm dev</code
        >
      </li>
      <li>
        Before opening a PR, add a changeset: <code
          class="rounded bg-kumo-control px-1 py-0.5 text-sm">pnpm changeset</code
        >
      </li>
      <li>Do not squash commits after review feedback starts.</li>
    </ul>

    <h3 class="mb-3 mt-6 text-xl font-semibold">Before Getting Started</h3>
    <p class="mb-4 text-kumo-strong">
      For non-trivial changes, engage on an issue first (or open a discussion or
      feature request) before writing code. For trivial changes, opening a PR
      directly is fine.
    </p>

    <h3 class="mb-3 mt-6 text-xl font-semibold">Set Up Your Environment</h3>
    <ul class="list-inside list-disc space-y-2 text-kumo-default">
      <li>
        Install the latest LTS version of <a
          href="https://nodejs.dev/"
          class="text-kumo-link hover:underline">Node.js</a
        > (we recommend a version manager like <a
          href="https://github.com/nvm-sh/nvm"
          class="text-kumo-link hover:underline">nvm</a
        >).
      </li>
      <li>
        Install a code editor (we recommend <a
          href="https://code.visualstudio.com/"
          class="text-kumo-link hover:underline">VS Code</a
        >) and project-recommended extensions.
      </li>
      <li>
        Install <a
          href="https://git-scm.com/"
          class="text-kumo-link hover:underline">git</a
        >.
      </li>
      <li>
        Install dependencies from the repository root with <code
          class="rounded bg-kumo-control px-1 py-0.5 text-sm">pnpm install</code
        >.
      </li>
    </ul>

    <h3 class="mb-3 mt-6 text-xl font-semibold">Fork and Clone</h3>
    <p class="mb-4 text-kumo-strong">
      External contributors should fork first and add <code
        class="rounded bg-kumo-control px-1 py-0.5 text-sm">cloudflare/kumo</code
      > as upstream. Cloudflare employees can clone the main repository directly.
    </p>
    <CodeBlock
      code={`# External contributors
git clone https://github.com/<your-github-username>/kumo
cd kumo
git remote add upstream https://github.com/cloudflare/kumo

# Keep your local main current
git switch main
git pull upstream main

# Cloudflare employees can clone directly
git clone https://github.com/cloudflare/kumo.git`}
      lang="bash"
    />

    <h3 class="mb-3 mt-6 text-xl font-semibold">Create and Push Your Branch</h3>
    <CodeBlock
      code={`git switch main
git pull upstream main
git checkout -b <new-branch-name> main

git add <paths-to-changed-files>
git commit
git push -u origin <new-branch-name>`}
      lang="bash"
    />
  </ComponentSection>

  <!-- Quality Checks -->
  <ComponentSection>
    <Heading level={2}>Quality Checks Before PR</Heading>
    <p class="mb-4 text-kumo-strong">
      Run the same core checks from <code class="rounded bg-kumo-control px-1 py-0.5 text-sm"
        >CONTRIBUTING.md</code
      > before opening or updating a PR.
    </p>
    <CodeBlock
      code={`pnpm run typecheck
pnpm run lint
pnpm run format
pnpm run test`}
      lang="bash"
    />
    <p class="mt-4 text-kumo-strong">
      If you recently rebased on <code class="rounded bg-kumo-control px-1 py-0.5 text-sm"
        >main</code
      >, run <code class="rounded bg-kumo-control px-1 py-0.5 text-sm"
        >pnpm i</code
      > first.
    </p>

    <h3 class="mb-3 mt-6 text-xl font-semibold">PR Expectations</h3>
    <ul class="list-inside list-disc space-y-2 text-kumo-default">
      <li>
        PR title format: <code class="rounded bg-kumo-control px-1 py-0.5 text-sm"
          >[package name] description</code
        >
      </li>
      <li>Fill out the full PR template with implementation details.</li>
      <li>
        Keep commit history clean before first review; after review starts,
        address feedback in follow-up commits instead of force-pushing rewrites.
      </li>
      <li>Include tests for new behavior.</li>
    </ul>
  </ComponentSection>

  <!-- PR, Changesets, and Releases -->
  <ComponentSection>
    <Heading level={2}>PRs, Changesets, and Releases</Heading>

    <h3 class="mb-3 mt-2 text-xl font-semibold">PR Review and Previews</h3>
    <ul class="list-inside list-disc space-y-2 text-kumo-default">
      <li>PR review is required for all changes.</li>
      <li>
        Every PR has package pre-release links via <a
          href="https://github.com/stackblitz-labs/pkg.pr.new"
          class="text-kumo-link hover:underline">pkg.pr.new</a
        > in an automated PR comment.
      </li>
    </ul>

    <h3 class="mb-3 mt-6 text-xl font-semibold">Changesets</h3>
    <p class="mb-4 text-kumo-strong">
      Every non-trivial change that should appear in changelogs needs a
      changeset.
    </p>
    <CodeBlock
      code={`pnpm changeset
git add .changeset/*.md`}
      lang="bash"
    />
    <p class="mt-4 text-kumo-strong">
      See <code class="rounded bg-kumo-control px-1 py-0.5 text-sm"
        >.changeset/README.md</code
      > for detailed guidance.
    </p>

    <h3 class="mb-3 mt-6 text-xl font-semibold">Styleguide</h3>
    <p class="mb-4 text-kumo-strong">
      Follow <a
        href="https://github.com/cloudflare/kumo/blob/main/STYLEGUIDE.md"
        class="text-kumo-link hover:underline">STYLEGUIDE.md</a
      > to keep contributions consistent.
    </p>

    <h3 class="mb-3 mt-6 text-xl font-semibold">Release Process</h3>
    <p class="mb-4 text-kumo-strong">
      Kumo releases are typically cut on weekdays. For out-of-band releases,
      contact the <a
        href="https://github.com/orgs/cloudflare/teams/kumo-maintainers"
        class="text-kumo-link hover:underline">kumo-maintainers</a
      > team.
    </p>
    <ol class="list-inside list-decimal space-y-2 text-kumo-default">
      <li>
        Merged changesets on <code class="rounded bg-kumo-control px-1 py-0.5 text-sm"
          >main</code
        > cause the Changesets bot to open or update a <strong>Version Packages</strong>
        PR.
      </li>
      <li>
        That PR bumps versions and aggregates changelog entries.
      </li>
      <li>Maintainers merge that PR to trigger publication to npm.</li>
    </ol>
  </ComponentSection>

  <!-- Component Scaffolding -->
  <ComponentSection>
    <Heading level={2}>Creating New Components</Heading>
    <p class="mb-4 text-kumo-strong">
      Kumo includes a scaffolding tool that automates component creation. This
      ensures all components follow the same structure and are properly
      configured.
    </p>

    <h3 class="mb-3 mt-6 text-xl font-semibold">Run the Scaffolding Tool</h3>
    <p class="mb-4 text-kumo-strong">From the workspace root, run:</p>
    <CodeBlock
      code={`pnpm --filter @cloudflare/kumo new-component`}
      lang="bash"
    />
  </ComponentSection>

  <!-- What It Does -->
  <ComponentSection>
    <Heading level={2}>What the Scaffolding Tool Does</Heading>
    <p class="mb-4 text-kumo-strong">
      The tool automatically creates and updates several files:
    </p>
    <ul class="mb-4 list-inside list-disc space-y-2 text-kumo-default">
      <li>
        <strong>Component file</strong> - <code
          class="rounded bg-kumo-control px-1 py-0.5 text-sm"
          >src/components/{"{name}"}/{"{name}"}.tsx</code
        >
      </li>
      <li>
        <strong>Index file</strong> - <code
          class="rounded bg-kumo-control px-1 py-0.5 text-sm"
          >src/components/{"{name}"}/index.ts</code
        >
      </li>
      <li>
        <strong>Story file</strong> - <code
          class="rounded bg-kumo-control px-1 py-0.5 text-sm"
          >src/components/{"{name}"}/{"{name}"}.stories.tsx</code
        >
      </li>
      <li>
        <strong>Test file</strong> - <code
          class="rounded bg-kumo-control px-1 py-0.5 text-sm"
          >src/components/{"{name}"}/{"{name}"}.test.tsx</code
        >
      </li>
      <li>
        <strong>Main exports</strong> - Updates <code
          class="rounded bg-kumo-control px-1 py-0.5 text-sm">src/index.ts</code
        >
      </li>
      <li>
        <strong>Build config</strong> - Updates <code
          class="rounded bg-kumo-control px-1 py-0.5 text-sm">vite.config.ts</code
        >
      </li>
      <li>
        <strong>Package exports</strong> - Updates <code
          class="rounded bg-kumo-control px-1 py-0.5 text-sm">package.json</code
        >
      </li>
    </ul>
  </ComponentSection>

  <!-- Example -->
  <ComponentSection>
    <Heading level={2}>Example</Heading>
    <p class="mb-4 text-kumo-strong">
      Here's what the scaffolding process looks like:
    </p>
    <CodeBlock
      code={`? Component name: Alert Banner

✅ Component scaffolded successfully!

📁 Files created:
   - src/components/alert-banner/alert-banner.tsx
   - src/components/alert-banner/index.ts
   - src/components/alert-banner/alert-banner.stories.tsx
   - src/components/alert-banner/alert-banner.test.tsx

📝 Files updated:
   - src/index.ts
   - vite.config.ts
   - package.json

💡 Import examples:
   import { AlertBanner } from "@cloudflare/kumo";
   import { AlertBanner } from "@cloudflare/kumo/components/alert-banner";`}
      lang="bash"
    />
  </ComponentSection>

  <!-- Naming -->
  <ComponentSection>
    <Heading level={2}>Component Naming</Heading>
    <p class="mb-4 text-kumo-strong">
      The scaffolding tool handles naming automatically. You can input the name
      in any format:
    </p>
    <ul class="mb-4 list-inside list-disc space-y-2 text-kumo-default">
      <li>
        <strong>Spaces</strong> - "Alert Banner" → <code
          class="rounded bg-kumo-control px-1 py-0.5 text-sm">alert-banner</code
        > directory, <code class="rounded bg-kumo-control px-1 py-0.5 text-sm"
          >AlertBanner</code
        > component
      </li>
      <li>
        <strong>PascalCase</strong> - "AlertBanner" → <code
          class="rounded bg-kumo-control px-1 py-0.5 text-sm">alert-banner</code
        > directory, <code class="rounded bg-kumo-control px-1 py-0.5 text-sm"
          >AlertBanner</code
        > component
      </li>
      <li>
        <strong>kebab-case</strong> - "alert-banner" → <code
          class="rounded bg-kumo-control px-1 py-0.5 text-sm">alert-banner</code
        > directory, <code class="rounded bg-kumo-control px-1 py-0.5 text-sm"
          >AlertBanner</code
        > component
      </li>
    </ul>
  </ComponentSection>

  <!-- Block Scaffolding -->
  <ComponentSection>
    <Heading level={2}>Creating New Blocks</Heading>
    <p class="mb-4 text-kumo-strong">
      Blocks are higher-level components that compose multiple base components.
      Use the block scaffolding tool to create them:
    </p>

    <h3 class="mb-3 mt-6 text-xl font-semibold">Run the Block Scaffolding Tool</h3>
    <p class="mb-4 text-kumo-strong">From the workspace root, run:</p>
    <CodeBlock code={`pnpm --filter @cloudflare/kumo new-block`} lang="bash" />

    <h3 class="mb-3 mt-6 text-xl font-semibold">What It Creates</h3>
    <p class="mb-4 text-kumo-strong">
      The block scaffolding tool creates the same structure as components, but
      in the <code class="rounded bg-kumo-control px-1 py-0.5 text-sm"
        >src/blocks</code
      > directory:
    </p>
    <ul class="mb-4 list-inside list-disc space-y-2 text-kumo-default">
      <li>
        <strong>Block file</strong> - <code
          class="rounded bg-kumo-control px-1 py-0.5 text-sm"
          >src/blocks/{"{name}"}/{"{name}"}.tsx</code
        >
      </li>
      <li>
        <strong>Index file</strong> - <code
          class="rounded bg-kumo-control px-1 py-0.5 text-sm"
          >src/blocks/{"{name}"}/index.ts</code
        >
      </li>
      <li>
        <strong>Story file</strong> - <code
          class="rounded bg-kumo-control px-1 py-0.5 text-sm"
          >src/blocks/{"{name}"}/{"{name}"}.stories.tsx</code
        >
      </li>
      <li>
        <strong>Test file</strong> - <code
          class="rounded bg-kumo-control px-1 py-0.5 text-sm"
          >src/blocks/{"{name}"}/{"{name}"}.test.tsx</code
        >
      </li>
      <li>
        <strong>Main exports</strong> - Updates <code
          class="rounded bg-kumo-control px-1 py-0.5 text-sm">src/index.ts</code
        > (Blocks section)
      </li>
      <li>
        <strong>Build config</strong> - Updates <code
          class="rounded bg-kumo-control px-1 py-0.5 text-sm">vite.config.ts</code
        >
      </li>
      <li>
        <strong>Package exports</strong> - Updates <code
          class="rounded bg-kumo-control px-1 py-0.5 text-sm">package.json</code
        >
      </li>
    </ul>

    <h3 class="mb-3 mt-6 text-xl font-semibold">Example</h3>
    <CodeBlock
      code={`? Block name: Navigation Bar

✅ Block scaffolded successfully!

📁 Files created:
   - src/blocks/navigation-bar/navigation-bar.tsx
   - src/blocks/navigation-bar/index.ts
   - src/blocks/navigation-bar/navigation-bar.stories.tsx
   - src/blocks/navigation-bar/navigation-bar.test.tsx

📝 Files updated:
   - src/index.ts
   - vite.config.ts
   - package.json

💡 Import examples:
   import { NavigationBar } from "@cloudflare/kumo";
   import { NavigationBar } from "@cloudflare/kumo/blocks/navigation-bar";`}
      lang="bash"
    />
  </ComponentSection>

  <!-- Layout Scaffolding -->
  <ComponentSection>
    <Heading level={2}>Creating New Layouts</Heading>
    <p class="mb-4 text-kumo-strong">
      Layouts are page-level components that provide consistent structure for
      common page patterns. Use the layout scaffolding tool:
    </p>

    <h3 class="mb-3 mt-6 text-xl font-semibold">Run the Layout Scaffolding Tool</h3>
    <p class="mb-4 text-kumo-strong">From the workspace root, run:</p>
    <CodeBlock code={`pnpm --filter @cloudflare/kumo new-layout`} lang="bash" />

    <h3 class="mb-3 mt-6 text-xl font-semibold">What It Creates</h3>
    <p class="mb-4 text-kumo-strong">
      The layout scaffolding tool creates the same structure as components and
      blocks, but in the <code class="rounded bg-kumo-control px-1 py-0.5 text-sm"
        >src/layouts</code
      > directory:
    </p>
    <ul class="mb-4 list-inside list-disc space-y-2 text-kumo-default">
      <li>
        <strong>Layout file</strong> - <code
          class="rounded bg-kumo-control px-1 py-0.5 text-sm"
          >src/layouts/{"{name}"}/{"{name}"}.tsx</code
        >
      </li>
      <li>
        <strong>Index file</strong> - <code
          class="rounded bg-kumo-control px-1 py-0.5 text-sm"
          >src/layouts/{"{name}"}/index.ts</code
        >
      </li>
      <li>
        <strong>Story file</strong> - <code
          class="rounded bg-kumo-control px-1 py-0.5 text-sm"
          >src/layouts/{"{name}"}/{"{name}"}.stories.tsx</code
        >
      </li>
      <li>
        <strong>Test file</strong> - <code
          class="rounded bg-kumo-control px-1 py-0.5 text-sm"
          >src/layouts/{"{name}"}/{"{name}"}.test.tsx</code
        >
      </li>
      <li>
        <strong>Main exports</strong> - Updates <code
          class="rounded bg-kumo-control px-1 py-0.5 text-sm">src/index.ts</code
        > (Layouts section)
      </li>
      <li>
        <strong>Build config</strong> - Updates <code
          class="rounded bg-kumo-control px-1 py-0.5 text-sm">vite.config.ts</code
        >
      </li>
      <li>
        <strong>Package exports</strong> - Updates <code
          class="rounded bg-kumo-control px-1 py-0.5 text-sm">package.json</code
        >
      </li>
    </ul>

    <h3 class="mb-3 mt-6 text-xl font-semibold">Example</h3>
    <CodeBlock
      code={`? Layout name: Dashboard Page

✅ Layout scaffolded successfully!

📁 Files created:
   - src/layouts/dashboard-page/dashboard-page.tsx
   - src/layouts/dashboard-page/index.ts
   - src/layouts/dashboard-page/dashboard-page.stories.tsx
   - src/layouts/dashboard-page/dashboard-page.test.tsx

📝 Files updated:
   - src/index.ts
   - vite.config.ts
   - package.json

💡 Import examples:
   import { DashboardPage } from "@cloudflare/kumo";
   import { DashboardPage } from "@cloudflare/kumo/layouts/dashboard-page";`}
      lang="bash"
    />
  </ComponentSection>

  <!-- Development Workflow -->
  <ComponentSection>
    <Heading level={2}>Development Workflow</Heading>
    <p class="mb-4 text-kumo-strong">
      After scaffolding a component, block, or layout, use the watch build setup
      to develop with the documentation site:
    </p>

    <div class="mb-6 rounded-lg border border-kumo-line bg-kumo-elevated p-4">
      <Heading level={3} class="mb-2 text-lg">Watch Build Setup</Heading>
      <p class="mb-3 text-sm text-kumo-strong">
        Run these commands in separate terminals for development with HMR:
      </p>
      <CodeBlock
        code={`# Terminal 1: Watch mode for kumo package
pnpm --filter @cloudflare/kumo dev

# Terminal 2: Documentation site dev server
pnpm dev`}
        lang="bash"
      />
      <ul class="mt-3 list-inside list-disc space-y-1 text-sm text-kumo-default">
        <li>Fast rebuild time (~400ms)</li>
        <li>Validates bundle exports/imports</li>
        <li>Tests actual build output</li>
        <li>See components in real documentation context</li>
      </ul>
    </div>

    <h3 class="mb-3 mt-6 text-xl font-semibold">Implementation Steps</h3>
    <ol class="list-inside list-decimal space-y-3 text-kumo-default">
      <li>
        <strong>Implement the component/block/layout</strong>
        <p class="ml-6 mt-1 text-kumo-strong">
          Edit the generated <code class="rounded bg-kumo-control px-1 py-0.5 text-sm"
            >.tsx</code
          > file in the kumo package.
        </p>
      </li>
      <li>
        <strong>Create demo file</strong>
        <p class="ml-6 mt-1 text-kumo-strong">
          Add a <code class="rounded bg-kumo-control px-1 py-0.5 text-sm"
            >{"{Name}"}Demo.tsx</code
          > file in <code class="rounded bg-kumo-control px-1 py-0.5 text-sm"
            >kumo-docs-astro/src/components/demos/</code
          > to showcase component variants.
        </p>
      </li>
      <li>
        <strong>Write tests</strong>
        <p class="ml-6 mt-1 text-kumo-strong">
          Add tests to the generated <code
            class="rounded bg-kumo-control px-1 py-0.5 text-sm">.test.tsx</code
          > file. Run tests in watch mode while developing.
        </p>
        <div class="ml-6 mt-2">
          <CodeBlock code={`pnpm --filter @cloudflare/kumo test`} lang="bash" />
        </div>
      </li>
      <li>
        <strong>Build the package</strong>
        <p class="ml-6 mt-1 text-kumo-strong">
          Before committing, do a full production build to ensure everything
          works:
        </p>
        <div class="ml-6 mt-2">
          <CodeBlock
            code={`pnpm --filter @cloudflare/kumo build`}
            lang="bash"
          />
        </div>
      </li>
      <li>
        <strong>Regenerate registry</strong>
        <p class="ml-6 mt-1 text-kumo-strong">
          Update the component registry to include examples from your demo file:
        </p>
        <div class="ml-6 mt-2">
          <CodeBlock
            code={`pnpm --filter @cloudflare/kumo codegen:registry`}
            lang="bash"
          />
        </div>
      </li>
      <li>
        <strong>Add documentation page</strong>
        <p class="ml-6 mt-1 text-kumo-strong">
          Create a documentation page in <code
            class="rounded bg-kumo-control px-1 py-0.5 text-sm"
            >kumo-docs-astro/src/pages/</code
          > showing real-world usage examples.
        </p>
      </li>
    </ol>
  </ComponentSection>

  <!-- Testing -->
  <ComponentSection>
    <Heading level={2}>Testing</Heading>
    <p class="mb-4 text-kumo-strong">
      The test suite automatically validates your component, block, or layout
      configuration:
    </p>
    <ul class="list-inside list-disc space-y-2 text-kumo-default">
      <li>Main entry point exports the component/block/layout</li>
      <li>
        Deep import paths work correctly (<code
          class="rounded bg-kumo-control px-1 py-0.5 text-sm"
          >@cloudflare/kumo/components/*</code
        >, <code class="rounded bg-kumo-control px-1 py-0.5 text-sm"
          >@cloudflare/kumo/blocks/*</code
        >, or <code class="rounded bg-kumo-control px-1 py-0.5 text-sm"
          >@cloudflare/kumo/layouts/*</code
        >)
      </li>
      <li>Package.json exports are properly configured</li>
      <li>Build configuration is correct</li>
      <li>All files exist in the correct locations</li>
    </ul>
    <p class="mt-4 text-kumo-strong">
      Run the test suite to ensure everything is configured correctly:
    </p>
    <CodeBlock code={`pnpm --filter @cloudflare/kumo test:run`} lang="bash" />
    <p class="mt-4 text-kumo-strong">
      The tests will provide helpful error messages with exact code snippets if
      any configuration is missing.
    </p>
  </ComponentSection>

  <!-- Component Guidelines -->
  <ComponentSection>
    <Heading level={2}>Component Guidelines</Heading>
    <p class="mb-4 text-kumo-strong">
      When implementing components, follow these guidelines:
    </p>
    <ul class="list-inside list-disc space-y-2 text-kumo-default">
      <li>
        <strong>Accessibility</strong> - Include proper ARIA attributes and
        keyboard navigation
      </li>
      <li>
        <strong>TypeScript</strong> - Export prop types and use proper type
        annotations
      </li>
      <li>
        <strong>Styling</strong> - Use Tailwind CSS classes and the <code
          class="rounded bg-kumo-control px-1 py-0.5 text-sm">cn</code
        > utility
      </li>
      <li>
        <strong>Consistency</strong> - Follow existing component patterns and
        naming conventions
      </li>
      <li>
        <strong>Documentation</strong> - Add clear JSDoc comments and usage
        examples
      </li>
      <li>
        <strong>Testing</strong> - Include unit tests for component behavior
      </li>
      <li>
        <strong>Single Responsibility</strong> - Keep components focused on one
        task
      </li>
    </ul>
  </ComponentSection>

  <!-- Block Guidelines -->
  <ComponentSection>
    <Heading level={2}>Block Guidelines</Heading>
    <p class="mb-4 text-kumo-strong">
      When implementing blocks, follow these additional guidelines:
    </p>
    <ul class="list-inside list-disc space-y-2 text-kumo-default">
      <li>
        <strong>Composition</strong> - Compose existing components rather than
        reimplementing functionality
      </li>
      <li>
        <strong>Framework Agnostic</strong> - Use <code
          class="rounded bg-kumo-control px-1 py-0.5 text-sm">LinkProvider</code
        > for routing to remain framework-agnostic
      </li>
      <li>
        <strong>Flexible Props</strong> - Accept both simple and complex props
        to support various use cases
      </li>
      <li>
        <strong>Common Patterns</strong> - Focus on patterns that appear in
        multiple applications
      </li>
      <li>
        <strong>Documentation</strong> - Include JSDoc explaining the block's
        purpose and when to use it
      </li>
      <li>
        <strong>Examples</strong> - Provide clear usage examples showing
        composition
      </li>
    </ul>

    <h3 class="mb-3 mt-6 text-xl font-semibold">When to Create a Block</h3>
    <ul class="list-inside list-disc space-y-2 text-kumo-default">
      <li>Pattern appears in multiple places across applications</li>
      <li>Combines 2+ base components</li>
      <li>Implements a common layout or page structure</li>
      <li>Has specific business logic or behavior</li>
    </ul>

    <h3 class="mb-3 mt-6 text-xl font-semibold">When NOT to Create a Block</h3>
    <ul class="list-inside list-disc space-y-2 text-kumo-default">
      <li>
        Single component with styling variations (use component variants
        instead)
      </li>
      <li>Application-specific logic (keep in application code)</li>
      <li>One-off patterns (wait for reuse before abstracting)</li>
    </ul>
  </ComponentSection>

  <!-- Resources -->
  <ComponentSection>
    <Heading level={2}>Additional Resources</Heading>
    <p class="mb-4 text-kumo-strong">
      For more detailed information, refer to:
    </p>
    <ul class="list-inside list-disc space-y-2 text-kumo-default">
      <li>
        <a
          href="https://github.com/cloudflare/kumo"
          class="text-kumo-link hover:underline">GitHub Repository</a
        >
      </li>
      <li>
        <a href="https://base-ui.com/" class="text-kumo-link hover:underline"
          >Base UI Documentation</a
        >
      </li>
    </ul>
  </ComponentSection>
</DocLayout>
