
sitecore-blok
Blok design system — catalog, setup, theming, MCP, and Marketplace integration.
- version
- 0.5.0
- GitHub stars
- 12
Install
/plugin install sitecore-blok@sitecore-skills-pocsRun it inside Claude Code after adding the marketplace with /plugin marketplace add Chris1415/sitecore-skills-pocs.
Contents
Discovered from sourceSkills 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 quickstart | NOT installed (common gotchas) |
|---|---|
alert, badge, button, card, collapsible, separator, skeleton | toggle-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@blokregistry entry incomponents.json— see theblok-setupskill, 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 withbg-primary+text-inverse-textfor the selected state,bg-muted+text-muted-foregroundfor the unselected state, andring-ringfor 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>.
| Blok | Purpose | Typical use |
|---|---|---|
topbar | Application topbar with logo, tenant switcher, user menu | Any Sitecore-styled app shell |
sidebar-rhs | Right-hand sidebar (properties, inspector, details) | Marketplace apps with a detail/edit pane |
site-card | Card showing a Sitecore site with metadata | Site lists, dashboards |
all-site-section | Section listing all sites | Landing / picker pages |
pinned-site-section | Section showing pinned/favorite sites | Dashboard home |
dashboard-widget | Framed widget for a dashboard | Custom Dashboard Blocks extension |
collaboration | Avatar stack + live presence indicators | Multi-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
- Is there a matching Blok? Prefer composites — they encode Sitecore UX patterns and save layout work.
- If not, pick a primitive. Compose primitives rather than reinventing.
- Only author custom markup when neither layer matches — and stay inside Blok tokens from the
blok-themingskill.
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.jsonnotButton.json. - Missing theme — components render without Blok colors when
theme.jsonwasn't installed first. See theblok-setupskill, 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-clientskill — SDK base - The
marketplace-sdk-lifecycleskill — extension points + app architecture - The
blok-setup,blok-components,blok-themingskills — Blok fundamentals
Extension point → Blok shell recommendation
| Extension point | Recommended shell | Notes |
|---|---|---|
| Full Screen | @blok/topbar + main content area + optional @blok/sidebar-rhs | Mirrors the Cloud Portal layout — users stay oriented |
| Pages Context Panel | No topbar; compact primitives (card, badge, separator, action-bar) | Narrow width — avoid bloks designed for full-width |
| Dashboard Blocks | @blok/dashboard-widget as the outer frame | One registration per block; widget frame is sized by portal host |
| Sites Context Panel | @blok/site-card variants + primitives | Matches 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 point | Typical width | Typical height |
|---|---|---|
| Full Screen | 1024–1920px | 600–1080px |
| Pages Context Panel | 320–400px | variable, scrollable |
| Dashboard Block | 300–800px | 200–400px |
| Sites Context Panel | 320–400px | variable |
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-areawrappers in panels or the whole app overflows - Large shadows clip at iframe edges — prefer
shadow-smin panel shells - Breakpoints — Blok's
md/lgbreakpoints 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.contextor equivalent from themarketplace-sdk-clientskill) and toggle the.darkclass on the iframe's<html>. - Never render a visible border/background that fights the portal chrome — Blok's
bg-backgroundis the safe default.
Auth + loading states
- Initial SDK handshake takes 100–500ms — show
@blok/skeletonplaceholders during this window, not a spinner - For empty tenants or missing permissions, use
@blok/empty-statesand@blok/error-stateswith 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.jsonwas 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 inpackage.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-componentsskill
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 UI | Query "what components exist?" during divergent proposals. Reference real component names in the UI design artifact. |
| Planning implementation | Use it to confirm a proposed component exists and to pull the current registry URL into the implementation plan. |
| Implementing | Use 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.jsonmissing the@blokregistry line (see § 4) - Prompt returns shadcn components instead of Blok → prompt didn't name the registry; prefix requests with
from the blok registryor@blok/* - MCP init silently updates files → commit
components.jsonand any MCP config changes after runningshadcn mcp initso 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
| Requirement | Minimum | Notes |
|---|---|---|
| Node.js | 16+ | shadcn CLI requirement |
| npm | 10+ | or pnpm/yarn equivalent |
| Tailwind CSS | v3 or v4 | must be configured before shadcn init |
| React | 18+ | primitives assume modern React |
| TypeScript | Recommended | registry 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
- Imports resolve via the
@/alias:import { Button } from "@/components/ui/button" - Tailwind classes apply Blok colors (e.g.
bg-primary,text-foreground) - 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.colors | Add --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 addso 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 { … }inapp/globals.cssinstead (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):
shadcnCLI used (version auto-resolved via@latest)components.jsonexists with@blokregistry entry- Components installed:
<list>(fromcomponents/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:
| Category | What it controls | Typical override need |
|---|---|---|
| Colors | Palette and base hues | Rare — Blok colors are the brand |
| Semantic tokens | Contextual roles (primary, destructive, muted, accent, background, foreground) | When a surface needs a non-default role |
| Typography | Font family, sizes, weights, line-heights | Rare — Blok ships the Sitecore type scale |
| Spacing | Margin/padding scale | Rare — stay inside the scale |
| Sizes | Component dimensional scale | When a component needs non-standard dimensions |
| Border radius | Corner rounding scale | Rare — radius is part of brand |
| Shadows | Elevation levels | Rare — elevation is part of brand |
| Breakpoints | Responsive breakpoints | When 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:
- Use semantic tokens directly.
bg-primary,text-foreground,border-destructive. These adapt automatically across themes and dark mode. - Scope CSS variable overrides to a container. If one page needs a muted surface, override
--backgroundon that container only. - Edit
theme.jsonequivalents in the global CSS. Only for project-wide brand adjustments — document the reason in the PRD or ADR. - 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
--primaryglobally — 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 theblok-setupskill --primary-foregroundcollapsed onto--primaryin dark — verify the pair resolves to a contrasting value in both themes before relying onbg-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 styledbg-primary, prefertext-backgroundas the label color, or scope a local--primary-foregroundoverride.
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,ifor info. These render as font glyphs and respectcolor. - Inline SVG with
currentColorfor 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