Docs, examples · Klarhimmel UI

Install

npx shadcn add @klarhimmel/docs-examples

Usage

import { Theme } from '@/components/klarhimmel/theme/style';
import { BlockSurface } from '@/components/klarhimmel/blocks/surface';
import DocsExamples from '@/components/klarhimmel/blocks/docs-examples';

export default function Section() {
  return (
    <Theme theme="brand">
      <BlockSurface>
        <DocsExamples props={{
          "title": "Examples",
          "description": "Each group changes one thing at a time.",
          "groups": [
            {
              "title": "Variants",
              "description": "Five styles. Use one primary button per view.",
              "preview": {
                "src": "",
                "alt": "Buttons in five variants"
              },
              "demo": "button-variants",
              "code": "<Button>Primary</Button>\n<Button variant=\"secondary\">Secondary</Button>\n<Button variant=\"ghost\">Ghost</Button>"
            },
            {
              "title": "Sizes",
              "description": "Small, medium and large. Every size keeps a 44 pixel hit area.",
              "preview": {
                "src": "",
                "alt": "Buttons in three sizes"
              },
              "demo": "button-sizes",
              "code": "<Button size=\"sm\">Small</Button>\n<Button size=\"md\">Medium</Button>\n<Button size=\"lg\">Large</Button>"
            },
            {
              "title": "States",
              "description": "Disabled buttons stay in the layout and are skipped by the keyboard.",
              "preview": {
                "src": "",
                "alt": "A button in default and disabled states"
              },
              "demo": "button-states",
              "code": ""
            }
          ]
        }} />
      </BlockSurface>
    </Theme>
  );
}

Install

Import

$import Block from '@/components/klarhimmel/blocks/docs-examples';

Also called

docs/examples

Category: Documentation sections: headers, install panels, props tables, previews.

Notes

When to use it

Stacks named example groups such as Variants, Sizes and States, each a stage with its code underneath. Use `docs-preview-frame` when there is only one example and a Preview and Code switch is enough.

Writing for it

- Group titles hold 40 characters and render as h3 under the block heading, so name the single thing that changes, like Sizes or With icon. - Code is allowed up to 2400 characters per group, which fits a whole demo including its imports. Leave it empty for groups where the picture says it all. - Order the groups from the default case to the edge cases, and use the group description (200 characters) to say when to choose that variant.

Watch out for

A group without code gets no code panel at all when published, so the stage sits alone in its frame. Between 1 and 8 groups are allowed, and a long page of them is better split into two blocks.

Pairs well with

Usage

The block in a page, with its default content (long lists shortened). Every prop is in the table below.

section.tsx

import { Theme } from '@/components/klarhimmel/theme/style';
import { BlockSurface } from '@/components/klarhimmel/blocks/surface';
import DocsExamples from '@/components/klarhimmel/blocks/docs-examples';

export default function Section() {
  return (
    <Theme theme="brand">
      <BlockSurface>
        <DocsExamples props={{
          "title": "Examples",
          "description": "Each group changes one thing at a time.",
          "groups": [
            {
              "title": "Variants",
              "description": "Five styles. Use one primary button per view.",
              "preview": {
                "src": "",
                "alt": "Buttons in five variants"
              },
              "demo": "button-variants",
              "code": "<Button>Primary</Button>\n<Button variant=\"secondary\">Secondary</Button>\n<Button variant=\"ghost\">Ghost</Button>"
            },
            {
              "title": "Sizes",
              "description": "Small, medium and large. Every size keeps a 44 pixel hit area.",
              "preview": {
                "src": "",
                "alt": "Buttons in three sizes"
              },
              "demo": "button-sizes",
              "code": "<Button size=\"sm\">Small</Button>\n<Button size=\"md\">Medium</Button>\n<Button size=\"lg\">Large</Button>"
            },
            {
              "title": "States",
              "description": "Disabled buttons stay in the layout and are skipped by the keyboard.",
              "preview": {
                "src": "",
                "alt": "A button in default and disabled states"
              },
              "demo": "button-states",
              "code": ""
            }
          ]
        }} />
      </BlockSurface>
    </Theme>
  );
}

Props

The type, default and text limit of every prop. On a real page, over-limit text is kept and checkSections flags it (Installation, Check a page before you ship); this live preview shows the default until it fits. The panel above edits all props.

Prop	Type	Default	Description
`title`	`string`	`'Examples'`	Text, up to 60 characters.
`description`	`string`	`'Each group changes one thing at a t…'`	Text, up to 200 characters.
`groups`	`{ title, description, preview, demo, code }[]`	`3 items`	List of 1 to 8. Each item: title, description, preview (optional), demo (optional), code.
`headingLevel`	`'1' \| '2'`	`-`	One of '1', '2'. Optional; empty is not rendered.