Block guidesConfigure · Customize · Check

Bring your app’s theme into every block

Bring a copied layout into the theme your application already uses. Blocks compose the same @kamod-ch/ui components and semantic tokens as individual controls. This guide focuses on sidebar surfaces, copied-source discovery and complete-screen checks, so you can adapt a composition without introducing another stylesheet or appearance system.

Start with the shared Theming & Tailwind reference for global CSS, preset overrides and runtime setup. Then use this companion to check --sidebar-background, distinguish preview settings from application preferences and verify overlays in both schemes. Add a Theme Toggle where it suits your layout; keep an explicit System option when users need it. For local spacing and hierarchy, continue with Component styles.

In this guide 6 sections

Theme foundations

Blocks inherit your application theme. They do not need a second theme system. Use the shared Theming & Tailwind reference for installation, CSS setup, semantic tokens, presets and runtime controls. This companion explains the extra checks that matter when those components become a complete screen.

Understand the appearance layers

Set up the foundation once at the application boundary, then let copied layouts consume it. Keep the block’s navigation state, routing and data separate from appearance preferences.

Your task	Start here
First Tailwind integration or missing utilities	Global CSS and source detection
Brand colors, radius, typography or presets	Shared token reference
Light, Dark, System or saved appearance	Appearance controls and first render
A copied sidebar or shell looks inconsistent	Continue with this guide
Local spacing, hierarchy or control variants	Component styles

Distinguish preview settings from app settings

The showcase’s theme and scheme controls affect its preview, independently of the documentation page. Their saved choices let you compare a variant, but copying source does not export those preferences, install fonts or add a theme picker to your app.

The preview’s device controls likewise do not define your application breakpoints. Test the copied block inside your real shell, where surrounding navigation, content and containers determine the available space.

Set up Tailwind and theme CSS

If your components already render correctly, keep that working setup. A copied block needs its class names included in the same build, not another Tailwind pipeline.

Choose a theme entry

The shared CSS guide explains the two theme entries. For these layouts, prefer @kamod-ch/themes/theme.css: it includes the sidebar mappings and preset values used by the block examples. A minimal component setup may need that fuller contract before a sidebar looks correct.

Connect Tailwind CSS v4

Keep Tailwind, the selected theme entry and application overrides in one global stylesheet. Follow the CSS-first setup if this is your first integration; do not add those imports again inside every copied block.

Make source detection explicit

Check where you placed the copied source. App-local files normally participate in discovery; shared workspace folders may need an explicit source path in addition to the installed UI package. Paths are relative to the stylesheet.

src/app.css

/* Add only if your copied layouts live in this workspace folder. */
@source "../../shared-layouts/src/**/*.{ts,tsx}";

This is an addition to an existing setup, not a complete stylesheet. Use the source detection reference for installed component paths and complete class strings. Build the app and check a class that occurs only in the copied block; a successful dev preview alone is not proof it reaches production CSS.

Shape your design with tokens

Theme the composition by role. A single screen can combine page, card, navigation and floating surfaces; making every region use the sidebar palette flattens that hierarchy.

Work with semantic token pairs

Use bg-background text-foreground for the page, bg-card text-card-foreground for content surfaces and the popover pair for floating menus. Keep the original component variants when they already express the correct intent. The token reference owns the complete contract and preset override examples.

Kamod uses --sidebar-background for the sidebar surface and --sidebar-outline for its focus treatment. A copied third-party palette using --sidebar or --sidebar-ring does not automatically configure those values.

Check navigation text, the selected row, hover feedback and keyboard focus together. Then open an account menu: its floating surface may consume popover tokens rather than sidebar tokens. The sidebar token table lists every mapping.

Customize a preset with tokens

Refine the app’s chosen preset in the global stylesheet. The following optional example adjusts only the sidebar surface pair; the shared reference explains the complete override pattern.

src/app.css

/* After the full theme import; applies only to the Ocean preset. */
:root[data-theme="ocean"] {
  --sidebar-background: oklch(0.97 0.01 250);
  --sidebar-foreground: oklch(0.25 0.03 250);
}

:root.dark[data-theme="ocean"] {
  --sidebar-background: oklch(0.2 0.02 250);
  --sidebar-foreground: oklch(0.95 0.01 250);
}

These values are a starting point, not an audited palette. Review the existing accent, border and focus colors against both new surfaces. Keep the preset choice at the app level so sibling pages use the same decisions.

Refine radius, typography and motion

After changing shared typography or radius, check long navigation labels, collapsed icon buttons, menu corners and form errors in the integrated screen. Load your own font assets; the preview’s fonts do not arrive with the source. Keep reduced-motion behavior when adapting transitions. See shared typography and motion guidance for the global setup.

Manage appearance preferences

Reuse your app’s existing appearance controls and provider. Copying another layout should not introduce a competing storage key, system-preference listener or app-wide theme controller.

Add preset and scheme controls

Put a Theme Toggle in an appropriate header, account menu or settings panel when a compact Light/Dark action is enough. Offer a scheme selector when users need an explicit System choice. The runtime guide contains complete provider and selector examples.

Theme state and sidebar state serve different purposes. Retain the block’s sidebar provider for collapse and mobile navigation, and let appearance come from the application theme. Check overlays as well as the sidebar when using a custom attributeTarget; a portal outside that target will not inherit its scoped variables.

Keep the first render consistent

Visit a nested application route directly with a saved dark preference. The shell, navigation and content should agree from the first paint. Configure the initialization script at the document boundary with defaults matching your provider, rather than adding scripts inside individual blocks.

Troubleshoot and verify

First determine whether the problem affects every component or only the copied composition. Shared failures belong in the theme troubleshooting reference; local ones usually involve copied source, scoped styles or container layout.

Diagnose theme problems in order

What you see	What to check in the block
Buttons look correct but the sidebar does not	Full sidebar token mappings and values, plus local background overrides.
A menu differs from its trigger	Popover tokens and whether the portal inherits the intended theme scope.
Only copied layout utilities are missing	Source discovery for the folder you copied or moved.
Your app differs from the showcase	App preset, stored scheme, loaded fonts and real container width.
A light region remains in dark mode	Hard-coded colors on wrappers or example content.
A nested route flashes the wrong appearance	Shared document initialization and provider defaults.

Finish with a theme review

Review the expanded and collapsed sidebar, mobile overlay, account menu and main content in both schemes. Use real names, long labels and form errors. Confirm visible focus and readable text on each surface, then refresh with saved settings and repeat the check in a production preview.

Keep theme configuration shared and layout behavior local. Return to Theming & Tailwind for foundation changes or Component styles to refine this composition’s hierarchy and spacing.

From reference to practiceBuild · Refine · Verify

Continue building

Put what you’ve learned into a small, working part of your app. Choose a composition, make one deliberate change and check the result with real content. You own the copied source: keep your Preact conventions, reuse the @kamod-ch/ui primitives and let your application supply the behavior.

Choose your next step

Continue with the part your screen needs next. Each guide takes you from a specific decision to a result you can check in your project.

Connect the composition

Choose one variant, copy its complete source and render it on a real route.

What you’ll haveA working first screen with your own navigation, data and service callbacks.

Getting started

Refine the details

Tune spacing, typography and action hierarchy around the content your users will see.

What you’ll haveA consistent layout that keeps the original keyboard and responsive behavior.

Component styles

Try one small change

These focused examples build on an already configured project. Use the suggested file paths as a starting point, adapt them to your folder structure and follow the selected block’s setup guide for its complete dependencies.

Style a surface that follows your theme

Use semantic tokens for a local content surface after your global theme import. Background and foreground belong together; a paired surface stays consistent when you change the preset or color scheme without a second set of hard-coded colors.

src/app.css

.project-panel {
  background: var(--card);
  color: var(--card-foreground);
  border: 1px solid var(--border);
  border-radius: var(--radius);
  padding: clamp(1rem, 3vw, 1.5rem);
}

.project-panel__description {
  color: var(--muted-foreground);
}

Check the result

Apply project-panel to a content container and project-panel__description to its supporting text. Check both schemes and your actual theme preset. Keep sidebar-specific surfaces on their own sidebar tokens.

CSS setup guide

Review in your app

Review the integrated screen, not just the isolated preview. Routes, services and your own content can expose issues that the demo never encounters. Use these four passes before you consider the composition ready.

Real content, real states: Replace demo names, links and sample data. Try long labels, empty results and failed requests; a successful demo state is only one part of the screen.
Keyboard from start to finish: Tab through the page, activate controls and dismiss overlays with Escape. Make sure focus remains visible and returns to the trigger after a menu or dialog closes.
Room to adapt: Check a narrow phone, a tablet and a wide desktop. Open the mobile navigation and try enlarged text. Keep controls reachable and confine wide tables or code to their own scroll area.
Both schemes, a fresh load: Review light and dark mode with your chosen preset. Reload a nested route directly and check the first render, text contrast, focus indicators and any saved preferences.

Check the build you actually ship

Inspect package.json and run the existing type, lint and test scripts that apply to your changes. For a project with a build script using pnpm, run pnpm run build, then serve the production output with your project’s preview command. Visit the route directly and check that copied files, assets and Tailwind utilities are included. A development preview alone does not verify the production result.