Keystatic Documentation

Keystar UI Primitives provides the foundational typography, sizing, and color tokens for the Keystar design system.

Note for Developers: The system is currently in development. It is acceptable to copy/paste tokens and manually adjust them as needed while the automation and validation workflows (such as Zod validation and Storybook previews) are being implemented.

You can extend the Keystatic editor by defining custom components for document fields or specialized content types like MDX/Markdoc. Components can be:

• block: A structural component that wraps content.
• inline: A component that lives within a line of text.
• mark: A component used for text highlighting/styling.

Components use a schema to define their own editable properties and a preview function to render how the component looks in the editor.

const components = {
  Highlight: mark({
    label: 'Highlight',
    icon: highlighterIcon,
    schema: {
      variant: fields.select({
        label: 'Variant',
        options: [
          { label: 'Fluro', value: 'fluro' },
          { label: 'Minimal', value: 'minimal' },
          { label: 'Brutalist', value: 'brutalist' },
        ],
        defaultValue: 'fluro',
      }),
    },
  }),
};

KeystarUI components are built around four core values:

• Accessible: Components are fully compatible with screen readers and support keyboard navigation.
• Responsive: Components support mouse, touch, and keyboard interactions and use responsive design to work across all devices.
• Adaptive: Components support both light and dark color schemes and can automatically adjust to the user's system settings.
• Inclusive: Components are engineered for a global audience, supporting features like right-to-left (RTL) language display and localized date and number formatting.

Keystatic provides two types of templates through the CLI:

1. Simple templates: Basic implementations with minimal dependencies, stored within the main monorepo.
2. Complex templates: Advanced examples stored in separate repositories to manage dependencies and assets efficiently.

All templates are published to npm and are downloaded by the CLI during the setup process. The CLI ensures that the template major version matches the CLI major version to prevent using out-of-date or incompatible cached versions.

The design system is organized into collections that support multiple modes (e.g., light and dark themes).

Current Collections

• color: Includes scales, aliases, backgrounds, foregrounds, icons, and shadows. Supports light and dark modes.
• size: Includes scales, borders, containers, dialogs, elements, icons, and radius/spacing.

Token Composition

Instead of using arbitrary t-shirt sizes for typography, the system aims to use semantic names (e.g., caption) that compose multiple properties into a single variant:

• color
• fontFamily
• fontSize
• fontWeight
• lineHeight
• textTransform

The built-in Remix app server is production-ready for Node.js environments. When deploying manually, ensure you include the output generated by remix build:

• build/
• public/build/

To start the development server and enable hot-reloading (rebuilding assets on file changes), run the following command from your terminal:

npm run dev

To run Keystatic or its development projects, ensure your environment meets the following requirements:

• Node.js: v18 or higher
• Package Manager: pnpm

If you encounter issues with pnpm, it is recommended to use corepack. You can enable it by running:

corepack enable pnpm

To start the development server for this project, use your preferred package manager to run the dev script. Once running, the application will be available at http://localhost:3000.

npm run dev
# or
yarn dev
# or
pnpm dev
# or
bun dev