@urbicon-ui/docs

@urbicon-ui/docs

Reusable documentation UI components — the pieces the Urbicon UI docs site is built from: page layout with scrollspy ToC, code examples with live preview, API/type reference tables, and an interactive prop playground. Part of the Urbicon UI monorepo.

Installation

bun add @urbicon-ui/docs @urbicon-ui/blocks @urbicon-ui/table @urbicon-ui/i18n @urbicon-ui/shared-types shiki @shikijs/langs

All of these (plus svelte ^5.57.1) are peer dependencies — the package bundles none of them:

• shiki (^4.4.3) + @shikijs/langs — syntax highlighting. CodePanel / CodeExample highlight through a shared, synchronous highlighter (highlighterService) with the package's editorial light/dark themes: Shiki's Sync core, its JavaScript regex engine, and ten statically imported grammars. Synchronous is the point — an awaited highlighter can only be driven from an effect, effects do not run during SSR, and the prerendered page then carries a spinner where the code should be. It also costs less over the wire: measured on this project's built bundles, ~333 → 121 KB gz for a page with code, because Vite inlines Shiki's oniguruma WASM as a 225 KB gz JavaScript chunk that the JS engine makes unnecessary. The eager half grows in exchange (44 → 121 KB gz); the full measurement is at the top of utils/highlighter.ts. Both are peers so your app controls the version and the grammars are not double-bundled next to an app-level install.
• @urbicon-ui/blocks — the components compose blocks primitives (Card, Badge, Button, …) and the semantic token layer.
• @urbicon-ui/table — ApiReference and TypesReference render their prop/type tables via <Table>.
• @urbicon-ui/i18n — built-in strings ship as a package-scoped docs.* namespace (EN/DE).
• @urbicon-ui/shared-types — PlaygroundConfigurator control definitions.

Styles

Import the stylesheets after Tailwind, blocks first — none of them imports Tailwind or each other (that stays the app's responsibility, and a stylesheet imported twice is emitted twice):

/* app.css */
@import 'tailwindcss';
@import '@urbicon-ui/blocks/style/index.css';
@import '@urbicon-ui/docs/style/index.css';
@import '@urbicon-ui/table/style/index.css'; /* table styles used by ApiReference/TypesReference */

Quick Start

<script lang="ts">
  import { Button } from '@urbicon-ui/blocks';
  import { CodeExample, DocsLayout, Section } from '@urbicon-ui/docs';

  const navigation = [
    { id: 'usage', title: 'Usage' },
    { id: 'api', title: 'API' }
  ];
</script>

<DocsLayout title="Button" description="Triggers an action." showToc {navigation}>
  <Section id="usage" title="Usage">
    <CodeExample title="Basic" language="svelte" code={`<Button intent="primary">Save</Button>`}>
      <Button intent="primary">Save</Button>
    </CodeExample>
  </Section>
</DocsLayout>

DocsLayout renders the page header (optionally with breadcrumbs, a stability badge, and a sourceHref link), a sticky scrollspy table of contents on desktop, and a collapsible ToC fallback on mobile. Section ids are the navigation anchors.

Vite plugin — no duplicated example code

The ./vite export ships codeExamplePlugin: for every <CodeExample isolate> it extracts the children markup at build time and injects it as the code prop — the live preview is the displayed source, written once.

// vite.config.ts
import { codeExamplePlugin } from '@urbicon-ui/docs/vite';

export default defineConfig({
  plugins: [codeExamplePlugin(), tailwindcss(), sveltekit({ adapter: adapter() })]
});

Components

Component	Purpose
DocsLayout	Page layout: header, breadcrumbs + collapsing sticky bar, stability badge, responsive ToC column
Section	Content section with anchor id, title/subtitle, badges, optional semantic footer
TableOfContents	Sticky "On this page" nav with scrollspy, optional related-links block and global code toggle
CodeExample	Code example with optional live preview, syntax highlighting, and copy-to-clipboard
CodePanel	Shared code-display primitive: Shiki highlighting, collapsible panel, auto line numbers, copy button
ApiReference	Structured props table (rendered via @urbicon-ui/table) with source/required badges and opt-in type links
TypesReference	Expandable type definitions with literal-value badges and cross-links to the API reference
PlaygroundConfigurator	Interactive prop playground: live preview, control panel, generated code
InfoCard	Memo-style callout card for notes and tips; renders as a link when href is set

Also exported: CodeVisibilityStore (+ context helpers) for a page-global expand/collapse-all-code toggle, ScrollSpy for active-section tracking, extractPlaygroundDocs / extractLiteralValues for deriving playground control metadata from generated API props, and highlighterService — the shared Shiki singleton the code components highlight through (highlightCode(code, language) returns a string, not a promise).

Styling

ApiReference, CodeExample, CodePanel, DocsLayout, PlaygroundConfigurator, TableOfContents, and TypesReference support unstyled + per-slot slotClasses, following the blocks styling conventions. Section and InfoCard are styled via variant props and class. All components accept class on the root element.

i18n

Built-in strings (copy buttons, ToC headings, playground labels) register as the docs.* namespace via @urbicon-ui/i18n, with EN/DE bundles. They resolve against the locale of a surrounding <I18nProvider> — or the base locale (en) when none is mounted, so the components work with zero i18n setup.

Development

bun --filter='@urbicon-ui/docs' run dev     # svelte-package watch
bun --filter='@urbicon-ui/docs' run build   # svelte-package
bun --filter='@urbicon-ui/docs' run test    # vitest
bun --filter='@urbicon-ui/docs' run check   # svelte-check

Related

• Urbicon UI docs site — its documentation chrome is built with these components
• @urbicon-ui/blocks — the component library these docs components compose
• @urbicon-ui/table — renders the API/type reference tables
• @urbicon-ui/i18n — locale provider the docs.* namespace plugs into