kickstartDS Premium Agency Starter

The kickstartDS Premium Agency Starter is a production-ready Design System and component library built on top of kickstartDS. It provides 80+ content components, a multi-theme token architecture, CMS page templates, full-text search, and rich Storybook integration — all tailored for digital agencies building marketing websites and landing pages.

This premium starter extends the open-source kickstartDS Content module with more visually rich, agency-focused components and a complete project scaffold including bundling, release automation, and prototyping tools.

Features

• 80+ Components: A comprehensive set of UI components for marketing pages — from heroes and CTAs to blog templates, event pages, and cookie consent.
• Multi-Theme Support: 5 pre-built themes (DS Agency, Business, Google, Telekom, NGO) with runtime switching via a single data-ks-theme attribute.
• Design Token Architecture: A layered token system with Branding Tokens, a Style Dictionary pipeline, and per-theme SCSS/CSS output.
• CMS Page Templates: Ready-to-use page-level schemas and components for headless CMS integration (Page, Blog Overview, Blog Post, Event Detail, Event List, Search, Settings).
• Storybook 8 Integration: Fully configured with addons for accessibility, design tokens, HTML output, JSON Schema, Playroom, component tokens, and Chromatic visual testing.
• Playroom Integration: Interactive prototyping environment with live component previews.
• Full-Text Search: Pagefind-powered search index generated from all Storybook stories.
• Cookie Consent: GDPR-compliant cookie consent with optional c15t integration.
• Bedrock Layouts: Bedrock Layout Primitives integrated with the Design System's spacing scale.
• Bundling: Rollup-based production build outputting ES modules, CSS, schemas, and static assets — usable with and without React.
• Release Automation: Semantic release handling via auto.
• Page Archetypes: Pre-composed page examples (Landing, About, Overview, Showcase, Jobs, Job Detail) demonstrating real-world usage.
• Token Playground: Interactive Storybook demos for visualizing color, typography, spacing, shadow, border, and transition tokens.
• Token Picker: Interactive picker to choose Design Tokens

Installation

Prerequisites

• Node.js — We recommend managing versions with nvm.
• Yarn — Used as the package manager.

As a dependency

yarn add @kickstartds/ds-agency-premium

Peer dependencies — You'll also need to install:

yarn add @kickstartds/base @kickstartds/blog @kickstartds/content @kickstartds/core @kickstartds/form react react-dom

Optional peer dependencies:

• c15t — For advanced GDPR cookie consent management
• tinycolor2 — For color manipulation utilities
• traverse — For JSON traversal utilities

From template

1. Create a new repository based on this template.
2. Clone and install dependencies: yarn install.
3. Update package.json with your project details.
4. Customize your branding (see Applying your Design / Brand).

Getting Started

# Start Storybook with hot reload (watches schemas, tokens, and code)
yarn start

# Start Playroom prototyping environment
yarn playroom

# Build Storybook for deployment
yarn build-storybook

# Build the library for publishing
yarn prepublishOnly

Key Scripts

| Script | Description | | ---------------------- | -------------------------------------------------------------------------- | | yarn start | Start Storybook dev server (port 6006) with file watchers | | yarn storybook | Start Storybook without watchers | | yarn playroom | Start Playroom with watchers | | yarn build-storybook | Build static Storybook site | | yarn build-tokens | Compile all theme tokens via Style Dictionary | | yarn init-tokens | Initialize tokens from branding token JSON | | yarn schema | Generate dereferenced schemas, TypeScript types, layer types, and defaults | | yarn token | Extract CSS custom properties from SCSS token files | | yarn branding-tokens | Build branding token CSS from JSON source files | | yarn search | Generate Pagefind search index from Storybook stories | | yarn presets | Generate component presets (JSX snippets) from stories | | yarn test | Run visual regression tests against Storybook | | yarn chromatic | Run Chromatic visual testing |

Components

The Design System includes 80+ components organized into several categories:

Content Components

| Component | Description | | ----------------- | -------------------------------------------------------------------- | | Button | Versatile button with label, icon, variant, size, and disabled state | | Button Group | Group of buttons with layout options | | CTA | Call to Action with headline, text, buttons, and alignment options | | Divider | Visual divider between content sections | | FAQ | Collapsible FAQ section with questions and answers | | Features | Feature grid/list with icons, titles, and descriptions | | Gallery | Image gallery with lightbox support | | Hero | Full-width hero banner with headline, text, image/video, and CTA | | Headline | Configurable headline with semantic level, style, and sub-headline | | Html | Raw HTML content block | | Image Story | Image with accompanying narrative text | | Image Text | Side-by-side image and text layout | | Logos | Logo strip / client logo showcase | | Mosaic | Tile-based mosaic layout for showcasing work | | Section | Page section wrapper with title, background, spacing, and layout | | Slider | Content carousel / slider | | Stats | Statistics display with animated counters | | Teaser Card | Card with image, headline, text, and link | | Testimonials | Testimonial display with author, quote, and image | | Text | Rich text content block | | Video Curtain | Full-width video background with overlay content | | Contact | Contact information display | | Downloads | Downloadable file listing | | Signpost | Directional signpost / link card | | Tile | Compact content tile | | Business Card | Personal/team member card | | Rich Text | Markdown-rendered rich text content |

Layout Components

| Component | Description | | ------------------ | ------------------------------------------------------- | | Split Even | Equal two-column split layout | | Split Weighted | Weighted split layout (e.g., sidebar + main content) | | Page Wrapper | Full page wrapper with header, footer, and content area | | Selection Rack | Selectable option layout |

Blog Components

| Component | Description | | --------------- | ---------------------------------------------------------------------- | | Blog Aside | Sidebar meta info for blog posts (author, sharing, reading time, date) | | Blog Author | Author bio display | | Blog Head | Blog post header with date, tags, headline, and cover image | | Blog Tag | Blog tag/category label | | Blog Teaser | Blog post preview card with image, excerpt, author, and metadata |

Event Components

| Component | Description | | ----------------------- | ------------------------------------------- | | Event Appointment | Event date/time display | | Event Filter | Filterable event categories | | Event Header | Event page header with title and categories | | Event Latest | Latest events showcase | | Event Latest Teaser | Compact latest event teaser | | Event List Teaser | Event listing card | | Event Location | Event venue/location display | | Event Login | Event access/login form | | Event Registration | Event registration form |

Navigation Components

| Component | Description | | ---------------- | ---------------------------------------------------------------- | | Header | Site header with logo, navigation, and actions | | Footer | Site footer with logo, navigation, legal links, and social icons | | Nav Main | Primary navigation menu | | Nav Dropdown | Dropdown navigation sub-menu | | Nav Flyout | Flyout navigation panel | | Nav Topbar | Top bar navigation strip | | Breadcrumb | Breadcrumb trail navigation | | Content Nav | In-page content navigation | | Pagination | Page navigation for lists |

Search Components

| Component | Description | | ----------------------- | --------------------------------- | | Search Bar | Search input with suggestions | | Search Filter | Faceted search filters | | Search Form | Complete search form | | Search Modal | Full-screen search overlay | | Search Result | Individual search result display | | Search Result Match | Highlighted text match in results |

Form Components

| Component | Description | | ----------------------------- | ------------------------------------- | | Checkbox / Checkbox Group | Checkbox inputs with group layout | | Radio / Radio Group | Radio button inputs with group layout | | Select Field | Dropdown select input | | Text Field | Single-line text input | | Text Area | Multi-line text input | | Form | Complete form wrapper |

Utility Components

| Component | Description | | -------------------- | ------------------------------------------------------------ | | Cookie Consent | GDPR-compliant consent banner with optional c15t integration | | SEO | SEO meta tag management | | Image / Lightbox | Image display with optional lightbox | | Page Teaser | Page-level teaser for internal linking |

CMS Page Templates

Pre-built page-level schemas and React components designed for headless CMS integration:

| Template | Description | | ----------------- | ----------------------------------------------------------------------------------------- | | Page | Generic page with sections, header/footer config, token overrides, and SEO | | Blog Overview | Blog listing page with latest post highlight, post grid, and CTA | | Blog Post | Individual blog post with sidebar (aside), content sections, and CTA | | Event Detail | Event detail page with locations, description, gallery, and downloads | | Event List | Filterable, paginated event listing with sidebar filters | | Search | Search results page with filters, search bar, and paginated results | | Settings | Global settings schema for header, footer, SEO defaults, icon sprite, and token overrides |

Each template includes a JSON Schema (.schema.json), dereferenced schema, TypeScript types, and default values — ready for integration with Sanity, Storyblok, Contentful, or any schema-driven CMS.

Themes

The Design System ships with 5 pre-built themes that can be switched at runtime:

| Theme | Token Path | Description | | ----------------------- | --------------------- | ------------------------------- | | DS Agency (default) | src/token/ | The base Systemics theme | | Business | src/token-business/ | Corporate business theme | | Google | src/token-google/ | Google-inspired theme | | Telekom | src/token-telekom/ | Deutsche Telekom-inspired theme | | NGO | src/token-ngo/ | Non-profit organization theme |

Themes are applied via a data-ks-theme attribute on <html> and can be switched at runtime using the useTheme hook. In Storybook, a toolbar dropdown lets you preview all themes live.

Pre-compiled theme CSS files are available in static/:

• tokens.css (default)
• tokens-business.css
• tokens-google.css
• tokens-telekom.css
• tokens-ngo.css
• tokens-lughausen.css

Token Playground

Interactive Storybook demos (under Token / Playground) for visualizing and testing design tokens:

• Color — Full color palette visualization
• Typography — Font family, size, weight, and line-height tokens
• Spacing — Spacing scale visualization
• Shadow — Box shadow token preview
• Border — Border radius tokens with live component previews
• Transition — Animation and transition token demos

Customizing

Applying your Design / Brand

To apply your branding and corporate design to kickstartDS, follow these steps:

1. Edit Branding Tokens — Update src/token/branding-token.json with your brand's primary colors, fonts, and base values. Multiple pre-built branding presets are also available (blizzard, burgundy, coffee, ember, granit, mint, neon, water).

2. Initialize tokens — Run yarn init-tokens to generate the full Design Token set from your branding values.

3. Fine-tune — Adjust the resulting token set in src/token/dictionary/ to closely fit your corporate identity (colors, spacing, typography, shadows, borders, transitions, background/text/border colors, and scaling).

4. Build — Run yarn build-tokens to compile all token variants and themes.

For a more in-depth overview of the token architecture, see:

• Foundations — Token
• Branding Token

Creating a New Theme

To create an additional theme:

1. Create a new token directory (e.g., src/token-mytheme/) with a dictionary/ folder and branding-token.json.
2. Create a Style Dictionary config file (e.g., sd.config-mytheme.cjs) following the pattern of existing configs.
3. Add a build script to package.json: "build-tokens-mytheme": "kickstartDS tokens compile --token-dictionary-path src/token-mytheme/dictionary --sd-config-path sd.config-mytheme.cjs".
4. Register the theme in src/themes/index.ts with a name, CSS path, and logo.

Adding Your Own Component

To add your own component, follow the guide "Create a component" or read about the ideas behind component creation. Here is a brief overview:

1. Create your component file — A .tsx file in src/components/my-component/. Follow the structure of existing components (functional React component with kickstartDS patterns).

2. Create your JSON Schema — A .schema.json file in the same directory defining the component API. TypeScript props are auto-generated from this schema via yarn schema.

3. Create Storybook stories — A .stories.tsx file with example stories for your component.

4. Register in Playroom — Add an export in src/playroom/components.ts to make the component available in Playroom.

5. Register in Providers — If the component uses React context, add it to src/components/Providers.tsx.

Architecture

Build System

• Rollup — Production library builds (ES modules to dist/), handling TypeScript, SCSS, JSON, schemas, and static assets.
• Vite — Powers Storybook dev server and Vitest test runner.
• Style Dictionary — Compiles design tokens from JSON to CSS/SCSS via the kickstartDS CLI.

Key Directories

| Path | Purpose | | --------------------- | -------------------------------------------------------------- | | src/components/ | All UI components (schemas, React, SCSS, stories) | | src/components/cms/ | CMS page template components and schemas | | src/pages/ | Pre-composed page archetypes for Storybook | | src/playground/ | Token visualization demo components | | src/themes/ | Theme registry and runtime switching | | src/token/ | Base design tokens and branding presets | | src/token-*/ | Per-theme token overrides | | src/types/ | Ambient type declarations for kickstartDS module augmentations | | src/bedrock/ | Bedrock Layout Primitives spacing integration | | scripts/ | Build tooling (token compilation, presets, search index, etc.) | | static/ | Pre-compiled CSS tokens, fonts, images, and Pagefind index | | docs/ | MDX documentation for design tokens in Storybook |

Provider Architecture

Components using React context are wrapped via a nested provider tree in src/components/Providers.tsx, mapping Design System components to their kickstartDS base counterparts (Button, Checkbox, Headline, Section, TeaserBox, and more).

Contributing

Contributions are welcome. Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as below, without any additional terms or conditions.

License

This project is licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT license (LICENSE-MIT)

at your option.

The SPDX license identifier for this project is MIT OR Apache-2.0.