Blok design system — catalog, setup, theming, MCP, and Marketplace integration.

version
0.5.0
GitHub stars
12

Install

/plugin install sitecore-blok@sitecore-skills-pocs

Run it inside Claude Code after adding the marketplace with /plugin marketplace add Chris1415/sitecore-skills-pocs.

Contents

Discovered from source

Skills 5

Blok Component Catalog

Blok ships in two layers:

  • Primitives — single-purpose components (Button, Input, Dialog). Fine-grained, composable.
  • Bloks — composite, opinionated blocks made from primitives (Topbar, Sidebar, Dashboard widget). Copy a Blok when you want a ready-made UI region.

All components are installed via the shadcn CLI. See the blok-setup skill for the install command form.

Canonical source: https://blok.sitecore.com/primitives and https://blok.sitecore.com/bloks. The lists below were captured on 2026-04-22 — re-verify before a client project, since the catalog grows.


Primitives (65+)

Install form: npx shadcn@latest add @blok/<name> (kebab-case).

Overlays & dialogs

accordion, alert, alert-dialog, collapsible, context-menu, dialog, dropdown, hover-card (if published), popover, sheet, tooltip, sonner (toast)

Forms & input

button, checkbox, combobox, command, date-picker, editable, field, filter, input, input-group, input-otp, label, radio-group, search-input, select, select-react-select, slider, switch, textarea, time-picker, toggle, toggle-group

Data display

avatar, badge, calendar, card, carousel, chart, circular-progress, empty-states, error-states, progress, skeleton, spinner, stepper, table, timeline

Layout & navigation

action-bar, aspect-ratio, breadcrumb, draggable, kbd, navigation-side, navigation-stack, navigation-menu, pagination, resizable, scroll-area, separator, tabs

Utility

icon

Full list and per-component docs: https://blok.sitecore.com/primitives.

What the Marketplace quickstart actually installs

The shadcn Marketplace quickstart registry URL (quickstart-with-client-side-xmc.json) only installs a subset of the primitive catalog. Inventory of components/ui/ from a fresh Scaffold 2 run (a Marketplace app build, 2026-04-22):

Installed by quickstartNOT installed (common gotchas)
alert, badge, button, card, collapsible, separator, skeletontoggle-group, radio-group, tabs, select, dialog, input, table, and most other primitives

Anything missing from the left column needs an explicit shadcn add after the scaffold. Re-inventory with ls components/ui/ on a fresh scaffold before trusting this list — the quickstart registry can drift.

toggle-group specifically — not installed by default

@blok/toggle-group is in the primitive catalog but is not pulled in by the Marketplace quickstart. If you need a segmented-control / radio-group-styled button row, you have two options:

  • Install it post-scaffold: npx shadcn@latest add @blok/toggle-group (requires the @blok registry entry in components.json — see the blok-setup skill, Step 3).
  • Compose a native button group styled with Blok semantic tokens. Use <button role="radio" aria-checked> for single-selection toggles or <button aria-pressed> for multi-selection toggles, and style with bg-primary + text-inverse-text for the selected state, bg-muted + text-muted-foreground for the unselected state, and ring-ring for keyboard focus. This keeps bundle size minimal and doesn't introduce a new registry dependency for a trivial UI pattern (one Marketplace app uses this approach for its viewport + height togglers).

Bloks (composite blocks)

Install form: npx shadcn@latest add @blok/<name>.

BlokPurposeTypical use
topbarApplication topbar with logo, tenant switcher, user menuAny Sitecore-styled app shell
sidebar-rhsRight-hand sidebar (properties, inspector, details)Marketplace apps with a detail/edit pane
site-cardCard showing a Sitecore site with metadataSite lists, dashboards
all-site-sectionSection listing all sitesLanding / picker pages
pinned-site-sectionSection showing pinned/favorite sitesDashboard home
dashboard-widgetFramed widget for a dashboardCustom Dashboard Blocks extension
collaborationAvatar stack + live presence indicatorsMulti-user editing views

Full list: https://blok.sitecore.com/bloks.


Graphics

Blok also provides Sitecore-branded graphics (icons, illustrations, logos) at https://blok.sitecore.com/graphics. These are not installed via the registry — they are downloaded or referenced from the site's brand portal. Check the Graphics page for the current delivery mechanism before using.


How to pick a component

  1. Is there a matching Blok? Prefer composites — they encode Sitecore UX patterns and save layout work.
  2. If not, pick a primitive. Compose primitives rather than reinventing.
  3. Only author custom markup when neither layer matches — and stay inside Blok tokens from the blok-theming skill.

Recording picks in the implementation plan

When planning implementation for a Marketplace app, the picked components go in the plan's scope/files section:

Blok components to install:
  Primitives: button, input, dialog, table, badge
  Bloks: topbar, sidebar-rhs
Registry URL: https://blok.sitecore.com/r/{name}.json
Install command: npx shadcn@latest add @blok/<name>

This gives the implementing developer everything they need without opening this file.


Pitfalls

  • Registry URL drift — always use {name}.json, kebab-case. button.json not Button.json.
  • Missing theme — components render without Blok colors when theme.json wasn't installed first. See the blok-setup skill, Step 2.
  • Using primitives when a Blok exists — composing a topbar from primitives recreates work Sitecore already did and misses accessibility refinements. Check the Bloks list first.
  • Legacy Chakra names leaking in — if a Stack Overflow answer says @chakra-ui/... or @sitecore/blok-theme, it is v1 and wrong for new work.

Blok × Marketplace SDK

Blok is the design system; the Marketplace SDK is the runtime. Together they produce Marketplace apps that look native to the Cloud Portal.

Load alongside:

  • The marketplace-sdk-client skill — SDK base
  • The marketplace-sdk-lifecycle skill — extension points + app architecture
  • The blok-setup, blok-components, blok-theming skills — Blok fundamentals

Extension point → Blok shell recommendation

Extension pointRecommended shellNotes
Full Screen@blok/topbar + main content area + optional @blok/sidebar-rhsMirrors the Cloud Portal layout — users stay oriented
Pages Context PanelNo topbar; compact primitives (card, badge, separator, action-bar)Narrow width — avoid bloks designed for full-width
Dashboard Blocks@blok/dashboard-widget as the outer frameOne registration per block; widget frame is sized by portal host
Sites Context Panel@blok/site-card variants + primitivesMatches Sites listing visual language

When the implementation plan lists components, match the extension point to the shell pattern above.


Iframe viewport constraints

Marketplace extension iframes are not full-viewport:

Extension pointTypical widthTypical height
Full Screen1024–1920px600–1080px
Pages Context Panel320–400pxvariable, scrollable
Dashboard Block300–800px200–400px
Sites Context Panel320–400pxvariable

See the marketplace-sdk-client skill, § 7, for authoritative numbers.

Implications for Blok choices:

  • Topbar only fits Full Screen reliably — it is too tall for panels
  • Tables need scroll-area wrappers in panels or the whole app overflows
  • Large shadows clip at iframe edges — prefer shadow-sm in panel shells
  • Breakpoints — Blok's md/lg breakpoints map poorly inside panels; treat panel shells as mobile-first

Theming inside iframes

  • The Cloud Portal passes theme preference (light/dark) into the iframe. Respect it — do not force one mode.
  • Read host theme via the Marketplace SDK (pages.context or equivalent from the marketplace-sdk-client skill) and toggle the .dark class on the iframe's <html>.
  • Never render a visible border/background that fights the portal chrome — Blok's bg-background is the safe default.

Auth + loading states

  • Initial SDK handshake takes 100–500ms — show @blok/skeleton placeholders during this window, not a spinner
  • For empty tenants or missing permissions, use @blok/empty-states and @blok/error-states with Marketplace-appropriate copy (refer users to the Cloud Portal, not to a marketing page)

Submission / public-app checklist (Blok-related)

Before submitting a Marketplace app for public listing:

  • theme.json was installed; no raw hex colors in component code
  • All primitives and bloks used are from the canonical registry (not copied from Stack Overflow / forked)
  • Dark mode tested at all iframe widths
  • RTL tested if the app targets non-LTR locales
  • No @sitecore/blok-theme (Chakra v1) dependency anywhere in package.json

Full submission requirements live in the marketplace-sdk-lifecycle skill, public-app submission sections.


Pitfalls

  • Using Topbar in a Context Panel — visually wrong and wastes vertical space; use primitives instead
  • Hardcoding iframe width — iframes are resized by the portal; use responsive Blok tokens, not w-[1024px]
  • Fighting the portal theme — users reported that apps with forced-light or forced-dark themes feel "foreign"; always honor the host preference
  • Missing SDK handshake during skeleton — Blok skeletons look right but if the SDK never connects, they persist forever; always pair skeletons with a timeout → empty-states / error-states

Blok MCP Server

Blok exposes its registry over the shadcn MCP server. Once configured, AI assistants can list available components, add them, and scaffold layouts entirely from prompts — no manual lookup of registry URLs.

When to use

  • User wants AI-assisted UI generation inside a Sitecore-styled project
  • A Marketplace app is being built and the user wants Claude/Cursor/Copilot to pick Blok components automatically
  • An agent needs to query "what Bloks exist?" without opening the blok-components skill

Prerequisite: Blok is already set up in the project — see the blok-setup skill. The MCP reads from components.json to know which registries to query.


1. Quick setup — Claude Code

Run at the project root:

npx shadcn@latest mcp init --client claude

This adds the shadcn MCP server to the project's Claude Code configuration. Verify by listing active MCP servers inside a Claude Code session — shadcn should appear.


2. Cursor setup

Add to .cursor/mcp.json at the project root:

{
  "mcpServers": {
    "shadcn": {
      "command": "npx",
      "args": ["-y", "shadcn@latest", "mcp"]
    }
  }
}

Then enable shadcn under Cursor Settings → MCP.


3. VS Code / GitHub Copilot

Use the same mcp command pattern in the Copilot MCP config. Blok's docs defer to the shadcn MCP docs for the exact schema — if it changes, re-check https://blok.sitecore.com/mcp.


4. Prerequisite — Blok registry in components.json

For the MCP to see Blok components (not just shadcn's core registry), components.json must declare the @blok registry:

{
  "$schema": "https://ui.shadcn.com/schema.json",
  "registries": {
    "@blok": "https://blok.sitecore.com/r/{name}.json"
  }
}

Without this line the MCP will only surface stock shadcn components.


5. Prompt patterns (canonical examples from Blok docs)

Ask any of these once the MCP is running:

Show me all available components in the blok registry.
What components are available from blok?
Find me a hero section from the blok registry.
Install @blok/button.
Add button, card and alert from the Blok registry.
Build a dashboard layout using blok components.
Create a contact form using components from the shadcn registry.

For agent-authored prompts, be explicit about which registry — blok — to avoid the MCP falling back to stock shadcn components that don't match Sitecore styling.


6. Agent guidance

When you are…How to use the Blok MCP
Designing UIQuery "what components exist?" during divergent proposals. Reference real component names in the UI design artifact.
Planning implementationUse it to confirm a proposed component exists and to pull the current registry URL into the implementation plan.
ImplementingUse prompts like Add @blok/topbar, @blok/sidebar-rhs to install everything the plan lists in one pass.

7. Pitfalls

  • MCP added but no Blok in results → components.json missing the @blok registry line (see § 4)
  • Prompt returns shadcn components instead of Blok → prompt didn't name the registry; prefix requests with from the blok registry or @blok/*
  • MCP init silently updates files → commit components.json and any MCP config changes after running shadcn mcp init so the team's setup stays reproducible
  • Blok docs change the exact command → always cross-check https://blok.sitecore.com/mcp before documenting a final install step for a client-facing project

Blok Setup

When to use

  • A new app has been scaffolded (Content SDK head, Marketplace app, or plain Next.js/Vite) and now needs Blok-styled UI
  • An existing app without Blok needs to adopt it
  • The user asks for UI matching "Sitecore design language", "Blok", or references Marketplace app visual consistency

Do not install Chakra or @sitecore/blok-theme — that's legacy Blok v1. Always use the shadcn registry path below.


Prerequisites

RequirementMinimumNotes
Node.js16+shadcn CLI requirement
npm10+or pnpm/yarn equivalent
Tailwind CSSv3 or v4must be configured before shadcn init
React18+primitives assume modern React
TypeScriptRecommendedregistry components ship with .tsx + types

For Next.js projects, Tailwind is enabled via the --tailwind flag at create-next-app time. For Vite projects, shadcn auto-detects Vite during init.


Step 1 — Initialize shadcn

npx shadcn@latest init

Follow the prompts:

  • Base color: pick any (Blok's theme overrides this in step 2)
  • CSS variables: yes (required — Blok theme uses CSS vars)
  • Import alias: default @/* is fine

This creates components.json at the project root.


Step 2 — Install the Blok theme

Run this before adding any component. The theme provides the CSS variables that all Blok primitives and bloks depend on.

npx shadcn@latest add https://blok.sitecore.com/r/theme.json

This writes Blok's color, typography, spacing, radius, and shadow tokens into your global CSS and Tailwind config.


Step 3 — Register the Blok registry (optional but recommended)

Adding Blok as a named registry in components.json lets you reference components as @blok/button instead of the full URL.

Edit components.json to add:

{
  "$schema": "https://ui.shadcn.com/schema.json",
  "registries": {
    "@blok": "https://blok.sitecore.com/r/{name}.json"
  }
}

After this, installs become:

npx shadcn@latest add @blok/button @blok/card @blok/dialog

Without the registry entry, use the full URL form: npx shadcn@latest add https://blok.sitecore.com/r/button.json.


Step 4 — Add components

Individual primitive:

npx shadcn@latest add @blok/button

Multiple at once:

npx shadcn@latest add @blok/button @blok/card @blok/dialog @blok/input

A full blok (composite block):

npx shadcn@latest add @blok/topbar
npx shadcn@latest add @blok/sidebar-rhs
npx shadcn@latest add @blok/dashboard-widget

See the blok-components skill for the full catalog.


Step 5 — Verify

  1. Imports resolve via the @/ alias: import { Button } from "@/components/ui/button"
  2. Tailwind classes apply Blok colors (e.g. bg-primary, text-foreground)
  3. Dev server renders a Button with Sitecore styling (rounded corners, Blok primary color)

If styling looks generic shadcn instead of Blok: the theme wasn't installed — re-run Step 2.


Fonts — Geist already ships with Nova preset

The Nova preset's scaffolded app/layout.tsx already loads Geist Sans and Geist Mono via next/font/google. Do not additionally npm install geist and import from geist/font/sans — that adds a parallel font loader that fights the scaffolded one (duplicate @font-face rules, two sets of CSS variables, flash of unstyled text on cold loads).

Instead: use the scaffolded next/font/google loader and, if your project / Tailwind layer expects the canonical --font-sans / --font-mono variable names, rename Next's emitted variables to those names:

// app/layout.tsx — scaffolded form, renamed to canonical variable names
import { Geist, Geist_Mono } from "next/font/google";

const geistSans = Geist({ variable: "--font-sans", subsets: ["latin"] });
const geistMono = Geist_Mono({ variable: "--font-mono", subsets: ["latin"] });

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body className={`${geistSans.variable} ${geistMono.variable} antialiased`}>
        {children}
      </body>
    </html>
  );
}

Heads-up: the scaffolded app/globals.css contains a self-referential token declaration that looks broken at first glance — something like:

--font-sans: var(--font-sans);

It is not a bug. The var(--font-sans) on the right-hand side is the variable that next/font/google publishes on the <body> (from geistSans.variable above); the --font-sans on the left is the Tailwind / Nova token consumers reference. The rule only becomes meaningful once app/layout.tsx sets the outer variable with a real font loader. A newcomer inspecting globals.css in isolation can spend five minutes staring at the no-op CSS rule before the layering clicks — flag it so future builders skip the detour.


Tailwind v4 / Nova preset — tokens live in CSS, not JS

Blok's Nova preset is Tailwind v4, which is CSS-first. There is no tailwind.config.ts in a scaffolded project (verify with ls — you won't find one). Design tokens (colors, shadows, motion, typography, spacing, radius) live in app/globals.css inside the @theme inline { … } block, not in a JS config file.

When an implementation plan, ADR, or code-review checklist references "extend the Tailwind config" or "add a color to tailwind.config.ts", that's Tailwind v3 language. Translate to v4 before acting:

v3 (legacy)v4 / Nova preset (current)
Extend colors in tailwind.config.ts → theme.extend.colorsAdd --color-<name>: …; inside @theme inline { … } in app/globals.css
Extend spacing / typography in theme.extend.*Add --spacing-<name> / --font-<name> inside @theme inline { … }
Declare keyframes in theme.extend.keyframes + animation in theme.extend.animation@keyframes <name> { … } at the top level of app/globals.css + --animate-<name>: <name> <duration> <easing>; inside @theme inline { … }
plugins: [require('tailwindcss-animate')]@import "tw-animate-css"; at the top of app/globals.css (the quickstart already does this)

No tailwind.config.ts file is present, needed, or correct to create for Nova preset work. If an implementation plan says "edit tailwind.config.ts", treat that as a doc bug and patch the token inside @theme inline { … } in globals.css instead.


Forbidden shortcuts

  • Do not npm install @sitecore/blok-theme — that's the deprecated Chakra v1 route
  • Do not copy components from the Blok site by hand — always use shadcn add so future updates are traceable
  • Do not skip the theme install — components will render with shadcn defaults (wrong colors, wrong radius)
  • Do not create a tailwind.config.ts "to extend Blok" — Nova is Tailwind v4; extend @theme inline { … } in app/globals.css instead (see section above)
  • Do not commit node_modules or the registry JSON; only the generated component files

Post-setup handoff

Record in your project's dependencies log (or the implementation plan's dependencies section):

  • shadcn CLI used (version auto-resolved via @latest)
  • components.json exists with @blok registry entry
  • Components installed: <list> (from components/ui/ directory)
  • Tailwind config file modified (Blok tokens merged)

No package-lock entry is added for Blok itself — it's code-owned, not dependency-managed.

Blok Theming

Blok's theme is applied via CSS variables + Tailwind config — installed in the blok-setup skill, Step 2, by adding theme.json. Do not override raw hex colors or font families in component files — change tokens at the theme level so the whole surface stays coherent.


Token categories

Per https://blok.sitecore.com/theming, Blok exposes 8 token categories:

CategoryWhat it controlsTypical override need
ColorsPalette and base huesRare — Blok colors are the brand
Semantic tokensContextual roles (primary, destructive, muted, accent, background, foreground)When a surface needs a non-default role
TypographyFont family, sizes, weights, line-heightsRare — Blok ships the Sitecore type scale
SpacingMargin/padding scaleRare — stay inside the scale
SizesComponent dimensional scaleWhen a component needs non-standard dimensions
Border radiusCorner rounding scaleRare — radius is part of brand
ShadowsElevation levelsRare — elevation is part of brand
BreakpointsResponsive breakpointsWhen the app has Sitecore-specific viewport ranges (e.g. iframe-constrained Marketplace apps)

Full per-category reference: https://blok.sitecore.com/theming.


Override strategy

Preferred order, from least invasive to most:

  1. Use semantic tokens directly. bg-primary, text-foreground, border-destructive. These adapt automatically across themes and dark mode.
  2. Scope CSS variable overrides to a container. If one page needs a muted surface, override --background on that container only.
  3. Edit theme.json equivalents in the global CSS. Only for project-wide brand adjustments — document the reason in the PRD or ADR.
  4. Never hardcode hex. bg-[#c41230] defeats the system — future theme updates won't reach that code.

Dark mode

Blok theme variables flip automatically under a .dark class on <html> (standard shadcn pattern). Use next-themes or equivalent — no Blok-specific provider needed.


RTL

Blok includes RTL support. See the RTL guide linked from https://blok.sitecore.com/resources. Enable via Tailwind's dir utilities or a dir="rtl" attribute on the root. Do not hardcode ml-* / mr-* — use ms-* / me-* (logical properties).


Iframe-specific theming (Marketplace apps)

Marketplace apps render inside an iframe in the Cloud Portal. Two token categories deserve extra attention:

  • Breakpoints — the iframe width is rarely full-viewport. Test at 800px, 1024px, 1440px widths explicitly.
  • Shadows — large shadows clip at iframe edges and look wrong. Prefer smaller elevations (shadow-sm, shadow) in app-shell surfaces.

See the blok-marketplace-integration skill for viewport constraints.


Agent guidance

  • When designing UI: Propose designs using semantic token names (primary, muted, destructive) — not hex codes. Designs that reference Blok tokens are directly implementable.
  • When implementing: If a UI design specifies a color that doesn't map to any Blok semantic token, stop and ask — don't invent a new token silently.
  • When testing: Cover both light and dark themes, plus RTL when the app supports non-LTR locales.

Pitfalls

  • Raw hex in components — breaks dark mode and future theme updates
  • Overriding --primary globally — cascades through every component; scope overrides to containers
  • Tailwind arbitrary values like h-[123px] — usually a smell that a size token was missed; check the Sizes category first
  • Missing theme.json — the #1 cause of "Blok doesn't look right" is forgetting Step 2 in the blok-setup skill
  • --primary-foreground collapsed onto --primary in dark — verify the pair resolves to a contrasting value in both themes before relying on bg-primary text-primary-foreground. The Nova preset has shipped with them collapsed in dark mode at least once (a Marketplace app, 2026-04-27 — a share-link strip rendered as an unlabeled pastel bar). When in doubt for buttons styled bg-primary, prefer text-background as the label color, or scope a local --primary-foreground override.

Color-emoji codepoints are CSS poison for state icons

❌ (U+274C), ✅ (U+2705), ⚠️ (U+26A0+FE0F), and similar emoji codepoints render as built-in colored bitmaps on most platforms. They ignore color: hsl(var(--destructive)) and any other CSS color, and they ignore dark/light theme entirely. One Marketplace app (2026-04-27) shipped with ❌ in card error states — the result was a giant red-and-white bitmap dominating the panel regardless of theme.

For state icons that must inherit theme color, use:

  • Monochrome glyphs — ✕ (U+2715) for error/close, ✓ (U+2713) for success, ! for warning, i for info. These render as font glyphs and respect color.
  • Inline SVG with currentColor for fill/stroke.
  • Lucide-react icons (already in Blok dependency tree) — <XCircle className="text-destructive" />.

Never use emoji codepoints for any UI element that needs to communicate state via theme color.

Sponsors

Details

Marketplace
Chris1415/sitecore-skills-pocs
Source
plugins/sitecore-blok
Category
Sitecore
License
Apache-2.0

More from Chris1415/sitecore-skills-pocs

All 8