Kiekkist
Menu
DE

Guide · React

Add a React template with Tailwind and shadcn/ui

The React export is not a finished project but a kit for yours: sections as TSX components, pages as components, tokens as CSS variables, a Tailwind theme and shadcn/ui variables.

In the example the design is Fieldnote (free, short name fieldnote). For your design, use its short name.

What you need

What is in the export

Folder fieldnote-react/

components/
One TSX component per section, copy in components/content/ as JSON, index.ts exports everything.
pages/
One component per page, each with meta: title, description, path and bodyClassName.
styles/tokens.css
Every design value as a CSS variable.
styles/theme.css
Tailwind v4 @theme from the tokens and the shadcn/ui variables (--background, --primary …) pointing at the tokens.
styles/site.css
The CSS of the sections.
styles/index.css
Everything in one file, for projects without Tailwind.
styles/fonts/
Fonts as woff2 with fonts.css and licence files.
public/assets/
Images and the design’s small script.
registry.json, r/
shadcn registry files for theme and sections.
AGENTS.md, DESIGN.md, EXPORT.md
Rules for AI assistants, design rules, export report.

By hand

  1. Download the ready export

    Free designs download from the design page, purchased ones from the download page with your licence key. Then choose what to load: React package, everything in one ZIP, or the design package only. Unpacked, the export sits in fieldnote/exports/react/, with INSTALL.md and EXPORT.md. It is the same content as fieldnote-react/ in the steps below.

  2. Or create it yourself

    To rebuild the export from a changed design package, use the Kiekkist tool kk. It is open source, runs locally and needs Node.js 22 or later. Put it next to the design folder (in the “design package only” download it is fieldnote/). The command writes fieldnote-react/; --no-check skips the visual comparison (for it, run npx playwright install chromium once).

    git clone https://github.com/tillheidrich/kiekkist
cd kiekkist && npm ci && cd ..
node kiekkist/cli/kk.js export ./fieldnote --target react --no-check

  3. Create a project (Vite)

    If you already have a project, skip this step.

    npm create vite@latest my-site -- --template react-ts
cd my-site
npm install
npm install -D tailwindcss @tailwindcss/vite

  4. Copy the files

    Copy styles/, components/ and pages/ from fieldnote-react/ to src/kiekkist/, and public/assets/ to public/assets/. Image paths start with /assets/.

  5. Add the Tailwind plugin

    In vite.config.ts:

    import tailwindcss from '@tailwindcss/vite'
// …
plugins: [react(), tailwindcss()]

  6. Import the CSS

    In src/index.css (already imported in main.tsx). Two things matter: include fonts.css, or the fonts are missing. And leave out Tailwind’s base reset (Preflight), or link underlines, for example, disappear. This keeps the page pixel-identical to the original:

    @layer theme, base, components, utilities;
@import "tailwindcss/theme.css" layer(theme);
@import "tailwindcss/utilities.css" layer(utilities);
@import "./kiekkist/styles/tokens.css";
@import "./kiekkist/styles/fonts/fonts.css";
@import "./kiekkist/styles/theme.css";
@import "./kiekkist/styles/site.css";

  7. Show a page

    Every page brings a class for <body> in meta.bodyClassName. Without it some styling is missing, such as the header over the hero image. In src/App.tsx:

    import { useEffect } from 'react'
import { IndexPage, IndexMeta } from './kiekkist/pages'

export default function App() {
  useEffect(() => {
    document.title = IndexMeta.title
    document.body.className = IndexMeta.bodyClassName
  }, [])
  return <IndexPage />
}

  8. Run and build

    For several pages, use a router of your choice and render the matching page component per route.

    npm run dev
npm run build

  9. Next.js (App Router)

    Copy the folders as above; without Tailwind, import '../kiekkist/styles/index.css' in app/layout.tsx is enough. Set <body className={IndexMeta.bodyClassName}> there and take metadata from IndexMeta. app/page.tsx returns <IndexPage />. Keep the fonts as local woff2 files; do not load them through next/font/google.

With an AI assistant

Your AI coding assistant can create the export, replace the sample content and tell you what is left for you to do. Give it the unpacked design folder and have it read these files:

  • fieldnote/DESIGN.md: design rules, colours, fonts, what not to change
  • fieldnote/tokens.json and tokens.css: every colour, type and spacing value
  • fieldnote/README.md: what is in the package and what to replace before launch
  • fieldnote/LICENSE.md: what you may do with code, copy and photos
  • fieldnote/UEBERGABE/: handover templates for your client (German and English)
  • in the export fieldnote-react/AGENTS.md and EXPORT.md

Prompt to copy. Replace the details in square brackets. Instead of fieldnote, use your design’s short name.

The folder ./fieldnote holds a website design as a package. Add it to my React project in ./[project] ([Vite or Next.js], [with or without Tailwind v4]). 1. Read fieldnote/DESIGN.md, README.md and LICENSE.md first. Do not change the design; use only token values, no Tailwind default colours. 2. Get the Kiekkist tool (git clone https://github.com/tillheidrich/kiekkist, then npm ci inside it) and create the export: node kiekkist/cli/kk.js export ./fieldnote --target react --no-check. Then read fieldnote-react/AGENTS.md and EXPORT.md. 3. Copy styles/, components/ and pages/ into the project and public/assets/ to public/assets/. Include styles/fonts/fonts.css. With Tailwind, import it without Preflight (tailwindcss/theme.css and tailwindcss/utilities.css) so the design does not change. 4. For every page, set meta.bodyClassName on <body> and the title and description from meta. Create routes for all pages. 5. Replace the sample copy in components/content/*.json with my details: [name, address, services]. 6. Build the project, fix errors and compare the home page with fieldnote/pages/index.html.

Have every change shown to you before it goes onto the live site. Passwords and licence keys do not belong in the chat or in the repository.

Replace content, images and logo

Copy: in components/content/sections/<section>.json and the lists next to it. Every component also takes props: <HeroRoom1 khA="New title" /> overrides the value from the JSON file.

Images: in public/assets/img/; the paths are in the JSON files. Same name and sizes, or change the paths. Update the alt texts too.

Logo: an SVG in SiteHeader.tsx and the per-page headers (*SiteHeader.tsx).

Adapt colours and fonts

The values exist twice: in styles/tokens.css (for the section CSS) and in styles/theme.css (for Tailwind classes like bg-paper). Both are generated from tokens.json. Cleanest way: change tokens.json in the design package, export again, replace both files.

The shadcn/ui variables in theme.css (--background, --foreground, --primary, --ring …) point at the tokens. shadcn components you add pick up the design’s colours and radii.

Tailwind’s default palette is switched off in theme.css (--color-*: initial). Classes like bg-blue-500 do not exist, only the design’s colours.

Fonts: the woff2 files in styles/fonts/ stay local. Do not load them from a font service.

What the licence allows

Purchased design: you may build unlimited websites with it, your own and your clients’, and hand them over with all rights. Your client may keep running the site without you. What is not allowed: passing on or selling the design itself, also not as a template, theme or kit. The full text is in the licence.

Free design: LICENSE.md in the package applies. For Fieldnote that is CC BY 4.0: use for clients and commercial work is fine, with a short credit in the source or on a credits page.

Photos from the package may only be used as part of the website you build with it. Do not pass them on separately or use them as stock.

Fonts are under the SIL Open Font License. Keep the licence files LICENSE-*.txt next to the font files.

Never put your licence key into a repository or theme files. KIEKKIST-LICENCE.txt in the package only names the licence ID and project.

Common problems

The fonts are missing; Arial or Georgia shows instead.

styles/fonts/fonts.css is not imported. Without Tailwind, styles/index.css includes it; with Tailwind you import it yourself (see above).

Links lost their underline; spacing looks different.

Tailwind’s Preflight resets browser defaults. Import Tailwind without Preflight (tailwindcss/theme.css and tailwindcss/utilities.css) as shown above.

Header or hero look different from the preview.

The class from meta.bodyClassName is missing on <body>. Set it per page.

Images are missing.

public/assets/ was not copied to public/assets/, or the app runs under a sub-path. The paths start with /assets/.

npx shadcn add with the registry file fails.

The files in r/ need a public address for npx shadcn add https://…/r/fieldnote-theme.json to find them. Locally, copying the folders is the simpler way.

The export stops with “export refused”.

kk checks the design before exporting and names every error with file and line, for example a section without a name. That happens when you changed the HTML pages in the package first. Fix the named spot, or export from the untouched package and change things afterwards. Also check your Node version with node -v: below 22 the tool does not run.

What we checked

Checked with Kestrel Row in a fresh Vite project (Vite 8, React 19, Tailwind 4.3, TypeScript 7): build without errors, home page pixel-identical to the HTML export. Plus a fresh Next.js 16 project without Tailwind: build without errors, home page checked in the browser.

More about this export All guides See the gallery

Other exports: WordPress, Astro, HTML, Elementor