Reading time: 20 min read
Exploring Sitecore’s Blok Design System
Go from zero to loaded with components in seconds.
What is a design system?
In this day and age, time is an extremely valuable resource. It can always feel like there is a greater and greater urgency to get a site, or even component, out the door and into the hands of a valued client. Some of that time can involve a developer getting up to speed on a client's product or service which is critical to being able to deliver value quickly. This is where design systems come in.
Here's the problem: without a design system, every project starts from scratch. Designers create similar buttons. Developers rebuild the same form across different projects. Colors don't match. Typography scales inconsistently. Padding! Don’t get me started on the issues of padding. Accessibility gets handled differently everywhere. What’s the result? Well, you end up with user experiences that don’t feel connected and a lot wasted effort. This results in bugs that you end up having to revisit later on. And perhaps a project manager displeased with the pace. Let alone the frustration, stress, and lack of confidence that comes with it.
A design system can help relieve that stress and frustration. Think of it as your single source of truth. A design system can be a shared library of standards, guidelines, and tools that everyone on the team uses. You get visual foundations (colors, typography, spacing), functional components (buttons, forms, navigation), and clear principles for how to use them. When done right, a button looks and behaves identically across every application. Color choices meet accessibility standards automatically. Designers and developers work from the same playbook.
Companies like Google (Material Design), Microsoft (Fluent), and IBM (Carbon) have proven this works. Their design systems let teams ship faster, maintain consistency, and their developers spend less time reinventing basic interface patterns and more time on new features.
Pair this with something like Storybook and your golden. At least in my opinion when it comes to delivering end results to clients.
What is Sitecore Blok design system?
Sitecore built Blok to solve exactly these problems for their ecosystem. It's their official design system. It’s a UI framework and style guide for building applications that work with Sitecore products and services because they use it as such. The general availability (GA) version takes a fresh approach, using modern tooling (Shadcn and Tailwind CSS) to make development faster while keeping everything visually consistent across all Sitecore products.
This is enormously valuable for partners and clients alike. Especially with SitecoreAI's new Marketplace. If you’re going to be building apps for your own purpose, your clients or looking to put on the Marketplace for others, getting that design to blend seamlessly is going to win your audience over.
What makes the Blok Design System better than other versions or even the previous Blok design system? Component ownership. Instead of installing packages from NPM that you can't touch, Blok components get installed directly into your codebase. Makes it super handy when you want to customize them. You can extend them however you need.
What makes up the Blok design system?
So what’s under the hood? Specifically, in terms of the newly released version, we have the following:
- Shadcn Foundation: Built on the popular Shadcn component system, which uses Radix UI primitives for accessibility
- Tailwind CSS: Utility-first CSS framework for rapid, consistent styling
- Vite-Ready: Optimized for modern build tools and fast development experiences
- Component Registry: Centralized registry for easy component installation and updates
- Style Guide: Comprehensive guidelines ensuring visual consistency across applications
- Design Resources: Tools and assets for both developers and designers to work in harmony
The general availability release of Blok represents a significant evolution in Sitecore's design system approach:
Shadcn integration
Shadcn is a component system that gives you flexibility and control of your components. Instead of installing packages, components are copied directly into your project. It’s handy because it you full control to customize them as needed. Obviously this has both pros and cons of course. It enables you, once setup, to just run with it and not have to worry about updating components or dealing with version conflicts. You can then evolve your design system as you go, and not have to worry about updating components or dealing with version conflicts.
Key benefits:
- Components live in your codebase, not in
node_modules - Full TypeScript support
- Built on Radix UI primitives for accessibility
- Easy to customize and extend whether it be things like padding, borders, colors, etc.
Tailwind CSS-first approach
Leveraging Tailwind CSS's utility-first methodology provides:
- Rapid Development: Build UIs faster with utility classes
- Consistent Styling: Design tokens baked into Tailwind configuration
- Responsive Design: Mobile-first responsive utilities out of the box
- CSS Variables: Dynamic theming with CSS custom properties
Component registry
Blok provides a centralized component registry making it easy to:
- Install individual components on demand
- Install the entire component library at once
- Keep components updated with the latest Sitecore design patterns
- Access both basic and advanced UI components
Enhanced foundations
Core design elements include:
- Colors: Comprehensive color palette with CSS variables
- Typography: Standardized text styles and hierarchies
- Design Tokens: Reusable values for colors, spacing, and other properties
- Icons: Modern icon system
- Logos: Sitecore product logos and brand assets
Getting started with Blok
So now you know a bit about Sitecore’s Blok, how about let’s set it up? It’ll just take a minute. The Shadcn CLI handles most of the configuration automatically.
Prerequisites
- Node.js and npm installed
- Tailwind CSS installed (if not, the CLI will help you set it up)
Installation steps
Once you’ve got your Sitecore AI foundation environment setup, you can proceed with getting Blok ready to go.
Step 1: Initialize Shadcn
Run the Shadcn initialization command in your project's root folder:
npx shadcn@latest init
During initialization, you'll be prompted to choose a base color. The CLI will then automatically:
- Detect your Vite or Next.js setup and Tailwind configuration
- Create a
components.jsonconfiguration file - Update your CSS with the necessary CSS variables
- Create
src/lib/utils.tswith utility functions - Set up path aliases for clean imports
What happens during initialization:
- The CLI detects your framework (React, Vite, etc.)
- Configures Tailwind CSS if needed
- Sets up the design system theme with CSS variables
- Prepares your project structure for component installation
Step 2: Install Blok components
You have two options for installing components:
Option A: Install Individual Components
Install specific components as you need them. For example, here’s how we could install the Button component:
npx shadcn@latest add https://blok.sitecore.com/r/button.json
This approach keeps your project lean by only including components you actually use.
Option B: Install All Blok Components (Recommended for most projects)
Install the complete Blok component registry to get access to all available components:
npx shadcn@latest add <https://blok.sitecore.com/r/blok-components.json>
This command will install a comprehensive set of components including:
- Basic UI Components: Button, Card, Input, Label, Badge, Avatar, etc.
- Advanced Components: Calendar, DataTable, Charts, Command Palette, etc.
- Layout Components: Navigation, Breadcrumbs, Sidebar, Header, etc.
- Form Components: Select, Checkbox, Radio, Switch, Textarea, etc.
- Feedback Components: Alert, Toast, Dialog, Progress, Skeleton, etc.
- Data Display: Table, List, Accordion, Tabs, Tooltip, etc.
Step 3: Test your setup
The following example looks at how you can verify a component has been installed correctly, but you would most likely use Storybook to get this organized and validated. I highly, highly recommend using Storybook to capture, monitor and demonstrate design choices as it makes managing changes very easy and can allow a client to see how a decision can impact more than they might think.
Blok Components Used:
Button- Demonstrates multiple variants
Update your src/App.tsx to test the installation. Components are imported with the @/ alias:
import { Button } from "@/components/ui/button";
export default function MyComponent() {
return (
<div className="p-8 space-x-4">
<Button variant="default">Primary</Button>
<Button variant="outline">Outline</Button>
<Button variant="ghost">Ghost</Button>
<Button variant="link">Link</Button>
</div>
);
}
Understanding the @/ alias: The @/ alias points to your src directory, making imports cleaner and more maintainable. Instead of ../../components/ui/button, you write @/components/ui/button.
Project structure after setup
After installation, your project will have the following structure:
your-project/
├── src/
│ ├── components/
│ │ └── ui/ # Blok components live here
│ │ ├── button.tsx
│ │ ├── card.tsx
│ │ ├── input.tsx
│ │ └── ...
│ ├── lib/
│ │ └── utils.ts # Utility functions (cn helper, etc.)
│ ├── App.tsx
│ └── index.css # CSS with design tokens
├── components.json # Shadcn configuration
├── tailwind.config.js # Tailwind configuration
└── package.json
For more detailed setup instructions and troubleshooting, visit the Blok documentation.
Available components in Blok
Blok offers an extensive collection of production-ready React UI components built on Shadcn and Tailwind CSS. These components are designed to accelerate development while ensuring consistency and accessibility.
Component categories
Basic UI components
The foundation of any interface, these components cover common UI needs:
- Button: Multiple variants (default, outline, ghost, link, destructive)
- Card: Container component with header, content, and footer sections
- Input: Text input fields with error states and labels
- Label: Accessible form labels
- Badge: Status indicators and tags
- Avatar: User profile images with fallback support
- Separator: Visual dividers for content sections
- Skeleton: Loading placeholders for better perceived performance
Example: Button Component
Blok Components Used:
Button- With variants: default, outline, ghost, destructive
import { Button } from "@/components/ui/button";
// Multiple variants available
<Button variant="default">Primary Action</Button>
<Button variant="outline">Secondary Action</Button>
<Button variant="ghost">Tertiary Action</Button>
<Button variant="destructive">Delete</Button>
Form components
Comprehensive form controls with built-in validation and accessibility:
- Select: Dropdown selection with search capabilities
- Checkbox: Single and grouped checkboxes
- Radio Group: Radio button groups
- Switch: Toggle switches for boolean values
- Textarea: Multi-line text input
- Form: Form wrapper with validation support
- Slider: Range input sliders
- Date Picker: Calendar-based date selection
Example: Form Component
Blok Components Used:
Input- For text inputLabel- For accessible form labelsButton- For form submission
import { Input } from "@/components/ui/input";
import { Label } from "@/components/ui/label";
import { Button } from "@/components/ui/button";
export function ContactForm() {
return (
<form className="space-y-4">
<div>
<Label htmlFor="email">Email</Label>
<Input type="email" id="email" placeholder="Enter your email" />
</div>
<Button type="submit">Submit</Button>
</form>
);
}
Navigation components
Help users navigate through your application:
- Breadcrumb: Hierarchical navigation trail
- Navigation Menu: Primary navigation with dropdowns
- Tabs: Content organization tabs
- Pagination: Page navigation for lists
- Command: Command palette (⌘K menu)
- Menubar: Application menu bar
Feedback components
Communicate status and information to users:
- Alert: Contextual feedback messages
- Toast: Temporary notification messages.
- Dialog: Modal dialogs for important actions
- Progress: Progress bars for loading states
- Spinner: Loading indicators
- Tooltip: Contextual help text
Data display components
Present information in structured and organized ways that are more easily accessible to readers and authors alike. Such as:
- Table: Data tables with sorting and filtering
- DataTable: Advanced tables with pagination
- Accordion: Expandable content sections
- Collapsible: Show/hide content areas
- Hover Card: Rich preview cards on hover
- Popover: Floating content panels
- Charts: Data visualization components
Advanced components
Complex components for sophisticated interfaces. Some of these we’re likely to see more broadly in tools like Pages which have to deal with various field types.
- Calendar: Date picker with month/year navigation
- Command Palette: ⌘K style command menu
- DataTable: Full-featured data tables with sorting, filtering, and pagination
- Combobox: Searchable select component
- Context Menu: Right-click context menus
- Dropdown Menu: Dropdown action menus
- Resizable: Resizable panel layouts
Component variants and customization
Each component comes with multiple variants to fit different use cases. Variants are, in Sitecore, a great and easy way for a client to switch a components style from one way to another. Think of them as “pre-made” styles. No need to adjust padding, colors, etc. Although there’s nothing stopping you from doing that. They can switch them simply from one background and foreground color to the next. Variants are also OOTB compatible with Personalization and A/B/n testing. Adjusting styles, etc don’t have that capability.
For example, the Button component includes:
default: Primary action buttonoutline: Secondary action with borderghost: Minimal styling for tertiary actionslink: Styled as a hyperlinkdestructive: For dangerous actions (delete, remove, etc.)
Accessibility built-in
All Blok components are built on Radix UI primitives, ensuring:
- Keyboard Navigation: Full keyboard support
- Screen Reader Support: Proper ARIA labels and roles
- Focus Management: Intelligent focus trapping and restoration
- Color Contrast: WCAG AA compliant color combinations
Building custom components with Blok
One of Blok’s greatest strengths as I’ve mentioned, is that the component code, is stored in your own file structure. This gives you complete control to customize and extend them. The design system provides the foundation through Tailwind CSS utilities and design tokens. There’s nothing stopping you now from modifying a particular component to suit your needs. Maybe you want buttons to have a specific animation. You can do that now quite easily.
Understanding the component architecture
Blok components follow the Shadcn philosophy:
- Components are yours: They're copied into your project, not installed as dependencies
- Full customization: Modify components directly to fit your needs
- Composition-first: Build complex UIs by composing simple components
- Tailwind-native: Use Tailwind utilities for styling
Design tokens with Tailwind CSS
Blok extends Tailwind's configuration with Sitecore-specific design tokens:
Colors
- Primary, secondary, accent colors via CSS variables
- Semantic colors: destructive, muted, accent
- Dark mode support out of the box
Spacing
- Tailwind's spacing scale (0-96, using 0.25rem increments)
- Consistent padding and margins
Typography
- Font sizes:
text-xs,text-sm,text-base,text-lg,text-xl, etc. - Font weights:
font-normal,font-medium,font-semibold,font-bold - Line heights automatically adjust with font sizes
Border Radius
rounded-sm: 0.125remrounded: 0.25remrounded-md: 0.375remrounded-lg: 0.5remrounded-xl: 0.75rem
Shadows
shadow-sm,shadow,shadow-md,shadow-lg,shadow-xl
Example: Building a hero banner component
Blok Components Used:
Button- For primary and secondary CTAsBadge- For eyebrow/label text
Here's a real-world example of building a production-ready component for Sitecore using Blok's design system. This HeroBanner component demonstrates composition, variants, and integration with Sitecore JSS:
import { ComponentProps, HeroBannerFields } from "@/types/sitecore";
import { Text, RichText, Link, NextImage } from "@sitecore-jss/sitecore-jss-nextjs";
import { Button } from "@/components/ui/button";
import { Badge } from "@/components/ui/badge";
export function HeroBanner({ fields }: ComponentProps<HeroBannerFields>) {
const {
heading,
subheading,
description,
eyebrow,
primaryCTA,
secondaryCTA,
badge,
variant = "default",
} = fields;
// Render different variants
if (variant === "gradient") {
return <HeroBannerGradient fields={fields} />;
}
// Default variant
return (
<section className="relative overflow-hidden bg-gradient-to-b from-white to-neutral-50 dark:from-neutral-950 dark:to-neutral-900">
<div className="container mx-auto px-4 py-24 lg:py-32">
<div className="max-w-4xl mx-auto text-center">
{/* Badge/Eyebrow */}
{(eyebrow || badge) && (
<div className="mb-6">
<Badge variant="default" className="text-sm px-4 py-1">
<Text field={eyebrow || badge} />
</Badge>
</div>
)}
{/* Heading with gradient text */}
<Text
tag="h1"
field={heading}
className="text-5xl md:text-6xl lg:text-7xl font-bold mb-6 bg-gradient-to-r from-neutral-900 via-neutral-700 to-neutral-600 dark:from-neutral-100 dark:via-neutral-300 dark:to-neutral-400 bg-clip-text text-transparent"
/>
{/* Subheading */}
{subheading && (
<Text
tag="p"
field={subheading}
className="text-xl md:text-2xl text-neutral-600 dark:text-neutral-400 mb-6"
/>
)}
{/* Description */}
<RichText
field={description}
className="text-lg text-neutral-600 dark:text-neutral-400 mb-8 max-w-2xl mx-auto"
/>
{/* CTAs */}
{(primaryCTA || secondaryCTA) && (
<div className="flex flex-wrap gap-4 justify-center mb-12">
{primaryCTA && (
<Button size="lg" asChild>
<Link field={primaryCTA} />
</Button>
)}
{secondaryCTA && (
<Button size="lg" variant="outline" asChild>
<Link field={secondaryCTA} />
</Button>
)}
</div>
)}
</div>
</div>
</section>
);
}
What this demonstrates:
- Sitecore JSS Integration: Using
<Text>,<RichText>, and<Link>components for field rendering - Component Composition: Combining Sitecore JSS components with Blok UI components (Button, Badge)
- Responsive Design: Mobile-first Tailwind utilities (
lg:py-32,md:text-6xl) - Dark Mode Support: Theme-aware classes (
dark:from-neutral-950) - TypeScript Integration: Proper typing with Sitecore's Content SDK
- Variant Pattern: Support for different layouts (default, gradient, split, image)
- Accessibility: Semantic HTML with proper heading hierarchy using
tagprop
Example 2: Adding variants to components
Blok Components Used:
Button- Customized with variant-specific stylingBadge- Semi-transparent styling for gradient background
Building on the HeroBanner, let's look at how to create variant layouts. Here's the gradient variant:
import { Text, RichText, Link } from "@sitecore-jss/sitecore-jss-nextjs";
// Gradient variant with full-width colored background
function HeroBannerGradient({ fields }: ComponentProps<HeroBannerFields>) {
const {
heading,
subheading,
description,
primaryCTA,
secondaryCTA,
badge,
stats,
} = fields;
return (
<section className="relative overflow-hidden bg-gradient-to-br from-blue-600 via-purple-600 to-pink-600">
{/* Overlay for better text contrast */}
<div className="absolute inset-0 bg-black/20" />
<div className="relative container mx-auto px-4 py-24 lg:py-32">
<div className="max-w-4xl mx-auto text-center text-white">
{badge && (
<Badge className="mb-6 bg-white/20 text-white border-white/30">
<Text field={badge} />
</Badge>
)}
<Text
tag="h1"
field={heading}
className="text-5xl md:text-6xl lg:text-7xl font-bold mb-6"
/>
{subheading && (
<Text
tag="p"
field={subheading}
className="text-xl md:text-2xl text-white/90 mb-6"
/>
)}
<RichText
field={description}
className="text-lg text-white/80 mb-8 max-w-2xl mx-auto"
/>
{/* Custom styled buttons for gradient background */}
{(primaryCTA || secondaryCTA) && (
<div className="flex flex-wrap gap-4 justify-center">
{primaryCTA && (
<Button
size="lg"
className="bg-white text-purple-600 hover:bg-neutral-100"
asChild
>
<Link field={primaryCTA} />
</Button>
)}
{secondaryCTA && (
<Button
size="lg"
variant="outline"
className="border-white/30 text-white hover:bg-white/10"
asChild
>
<Link field={secondaryCTA} />
</Button>
)}
</div>
)}
</div>
</div>
</section>
);
}
Best practices:
- JSS Field Types: Import
Field,ImageField,LinkFieldfrom@sitecore-jss/sitecore-jss-nextjs - Generic Field Type: Use
Field<string>for text and rich text fields - Built-in Types: Use JSS's
LinkFieldandImageFieldfor complex fields - Optional Fields: Use
?for fields that might not be populated in Sitecore - Generic Props:
ComponentProps<T>wrapper for consistency across components - Variant Types: Union types for finite layout options
The cn utility function
You’ve likely seen it being used more and more, but the cn() is invaluable for keeping your code and styling clean. So why use cn()?
- Merges Tailwind classes intelligently
- Handles conditional classes cleanly
- Prevents class conflicts
Example usage:
<div
className={cn(
"px-4 py-2 rounded-md", // base styles
isActive && "bg-primary text-white", // conditional
className // allow prop override
)}
/>
Best practices for custom components
Component Composition: Build complex components by composing Sitecore JSS and Blok components
// Good: Compose JSS field components with Blok UI components <section className="py-24"> <Badge variant="default" className="mb-6"> <Text field={badge} /> </Badge> <Text tag="h1" field={heading} className="text-5xl font-bold mb-6" /> <Button size="lg" asChild> <Link field={primaryCTA} /> </Button> </section> // Avoid: Accessing field values directly <h1 className="text-5xl">{heading.value}</h1> <a href={primaryCTA.href}>{primaryCTA.text}</a>Use Design Tokens: Reference theme colors, not arbitrary values
// Good: Use theme colors <div className="text-primary bg-secondary"> // Avoid: Arbitrary colors <div className="text-[#0066cc] bg-[#f5f5f5]">Responsive Design: Mobile-first approach
<div className="text-sm md:text-base lg:text-lg">Dark Mode Support: Use theme-aware classes
<div className="bg-white dark:bg-slate-900">Accessibility: Include proper ARIA labels and keyboard navigation
<Button aria-label="Close dialog" onClick={onClose}> <X className="h-4 w-4" /> </Button>
Customizing existing components
Since components live in your codebase, you can directly modify them:
- Navigate to
src/components/ui/button.tsx - Modify the variants, add new ones, or change styling
- Your changes are immediate and version-controlled
Example: Adding a new button variant
Blok Component Being Customized:
Button- Adding a custom "success" variant
// src/components/ui/button.tsx
const buttonVariants = cva("inline-flex items-center justify-center...", {
variants: {
variant: {
default: "bg-primary text-primary-foreground...",
outline: "border border-input...",
// Add your custom variant
success: "bg-green-500 text-white hover:bg-green-600",
},
},
});
Coding guidelines
For comprehensive coding standards, visit the Blok resources, which cover:
- Component structure and organization
- Naming conventions
- Prop patterns
- Accessibility requirements
- Performance considerations
- TypeScript best practices
Documentation sites
Technical documentation is one of those things that not only gets neglected but also tough to be consistent in a way that your clients can feel confident in returning to. You need excellent typography, clear hierarchy, intuitive navigation and consistency. Components like Tabs and Accordions make complex topics scannable instead of overwhelming. Card components and CTAs can can help bring attention to important material or changes that should be understood quickly.
Why This Matters for SitecoreAI
If you use Blok for your documentation, you're automatically consistent with the broader SitecoreAI environment. It will help your clients feel like you’re in line with the ecosystem they are so reliant on. So why does this matter?
- Familiarity: Developers who use SitecoreAI will instantly feel at home in your docs. Same patterns, same behaviors, same visual language. This reduces cognitive load significantly.
- Trust: Your documentation looks like it belongs in the official Sitecore family. That builds credibility.
- Alignment: Typography scales, color meanings, spacing. Everything matches what users already expect from Sitecore AI’s tools.
- Maintenance: When Sitecore updates Blok, you can update with them. You're not maintaining a custom design system. Although you may need to make tweaks to your local implementation as you’re not using hosted / module based components.
Whether you're building developer docs, API references, component libraries, or knowledge bases, using Blok means your content gets the same polish that defines the SitecoreAI experience. And that's valuable.
Future of Blok
Blok is actively evolving based on community feedback and Sitecore's design direction:
Planned enhancements
- More Components: Additional specialized components for common Sitecore use cases
- Enhanced Theming: More sophisticated theme customization options
- Design Tool Integration: Tighter integration with Figma and other design tools
- Advanced Patterns: More complex component compositions and recipes
- Performance Optimizations: Continued focus on bundle size and runtime performance
Staying updated
As Blok evolves, updating your components is straightforward:
- Run the Shadcn add command again for specific components
- Review the changes (they're just files in your project)
- Merge updates or keep your customizations
Because components live in your codebase, you have complete control over when and how to adopt changes.
Getting started
Ready to try the Blok design system? You won’t regret it. Follow the above steps to get started. Here's a summarized version of what we covered.
- Visit blok.sitecore.com
- Run
npx shadcn@latest initin your project - Install components:
npx shadcn@latest add https://blok.sitecore.com/r/blok-components.json - Import and use them
- Review the examples in this article
- Customize as needed
Give feedback
Blok Beta is actively being developed, and Sitecore wants to hear from you. Be active in the community by sharing what works (and what doesn't) via the community Slack. Follow that up and share your challenges or issues via support tickets. The more active we are the better the system can be. It’s why Sitecore has put it out there.
Additional resources
Blok design system
- Blok design system: blok.sitecore.com
- Official Site: blok.sitecore.com
- Resources: blok.sitecore.com/resources
- Resources: blok.sitecore.com/resources
Core technologies
- Shadcn: ui.shadcn.com - Component system and philosophy
- Tailwind CSS: tailwindcss.com - Utility-first CSS framework
- React: react.dev - JavaScript library for building user interfaces
Icon libraries
- Lucide React: lucide.dev - Beautiful & consistent icon toolkit
- Radix Icons: icons.radix-ui.com - Icon library from Radix UI
Community resources
- Tailwind UI: tailwindui.com - Official Tailwind CSS component examples
- Shadcn Examples: Browse community examples and patterns
- Sitecore Community: Connect with other Sitecore developers
As a reminder
This article covers the Blok design system as of December 2025. Features and capabilities may evolve as the system continues development. Always refer to the official Blok design system documentation at blok.sitecore.com for the most up-to-date information.