npm package: @netlify/spark-ui
Description: Assets, design tokens, components, and utilities
Latest version: 1.20.1

# Netlify Spark UI

Foundational design tokens, components, utilities, and other global assets to be shared across Netlify sites.

- **Assets** - logos, fonts, and more
- **Components** - [Astro](https://astro.build/) component library
- **Styles** - Element and component CSS
- **Utils** - Collection of JS utility functions

## Versioning

When commmits are merged into `main`, a new release will be created via GitHub Action. [semantic-release](https://semantic-release.gitbook.io/semantic-release) uses the commit messages to determine the impact of changes in the codebase. Follow [the commit message format](https://semantic-release.gitbook.io/semantic-release#commit-message-format) to properly version updates.

```bash
<type>[optional scope]: <description>

[optional body]

[optional footer(s)]
```

| Commit message                                                                                                           | Release type                                                                                                 |
| ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ |
| fix: corrects prop types                                                                                                 | ~~Patch~~ Fix Release                                                                                        |
| feat: add sparkCool feature                                                                                              | ~~Minor~~ Feature Release                                                                                    |
| perf: remove sparkCool feature<br><br>BREAKING CHANGE: The sparkCool option has been removed due to performance reasons. | ~~Major~~ Breaking Release<br><br>(Note that the BREAKING CHANGE: token must be in the footer of the commit) |

Check out [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) for other commit message types.

### Troubleshooting

Check that npm and GitHub tokens have not expired. Both are used in the [Release GitHub Action](https://github.com/netlify/netlify-spark-ui/blob/main/.github/workflows/release.yml#L34-L35) job.

## Code Quality

### Linting

This project uses ESLint to maintain code quality and consistency. To run the linter, use the following command:

```bash
npm run lint
```

### Code Formatting

Prettier is used to format the code. To format the codebase, run:

```bash
npm run format
```

## Design Tokens

Tokens provide a shared foundation of colors, typography, spacing, and more for our sites and apps. All token information is stored in the `/packages/tokens` directory. These aim to follow standards proposed in the [Design Tokens Format Module](https://tr.designtokens.org/format/).

Tokens are converted into CSS variables using the [terrazzo](https://terrazzo.app/) tool.

### Rebuild CSS token variables

When any files in this tokens directory are updated and merged into the `main` branch, the [build-tokens-css](https://github.com/netlify/netlify-bits/blob/main/.github/workflows/build-tokens-css.yml) GitHub Action is executed. This runs the `build:tokens` script, recreating the [tokens.css](https://github.com/netlify/netlify-bits/blob/main/packages/styles/tokens.css) file with updated CSS variables.

The tokens file can also be rebuilt manually with the following command:

```bash
npm run build:tokens
```

### Token Prefix and Backwards Compatibility

All design tokens are generated with a `--ntl-` prefix (e.g., `--ntl-color-bg`, `--ntl-font-size-display-lg`). If your project still references the older unprefixed token names (e.g., `--color-bg`), you can import the compatibility file to alias them:

```css
@import '@netlify/spark-ui/styles/tokens.css';
@import '@netlify/spark-ui/styles/tokens.compat.css';
```

`tokens.compat.css` maps every unprefixed variable name to its `--ntl-` prefixed equivalent across all theme selectors (`:root`, `prefers-color-scheme`, `[data-theme]`). This lets you incrementally migrate pages to the new prefixed tokens without breaking existing styles.

Once a page or project has been fully updated to use `--ntl-` prefixed tokens, remove the `tokens.compat.css` import.

### Layout Utility Prefix and Backwards Compatibility

Layout utility classes have been renamed from `.n-` to `.ntl-` (e.g., `.n-grid` → `.ntl-grid`, `.n-flow` → `.ntl-flow`). The associated CSS custom properties have also been renamed (e.g., `--n-grid-column-min-size` → `--ntl-grid-column-min-size`).

If your project still uses the old `.n-` class names or `--n-` layout variables, import the compatibility file:

```css
@import '@netlify/spark-ui/styles/layout.css';
@import '@netlify/spark-ui/styles/layout.compat.css';
```

`layout.compat.css` re-declares each old `.n-` class with the same styles, accepting both old `--n-` and new `--ntl-` CSS variables. This lets you incrementally migrate to the new prefixed names without breaking existing layouts.

Once all references have been updated to use `ntl-` prefixed classes and variables, remove the `layout.compat.css` import.

## Local Testing

During development, you should create a documentation page for your component inside the `/docs` directory. This allows you to test and showcase all its configurations and variations in isolation. Once you’re ready to test the component inside your frontend application, you can link your local `netlify-spark-ui` package using `npm link`.

### Setup Local Link

1. **Create a global link in your local `netlify-spark-ui` directory:**

   ```bash
   npm link
   ```

2. **Link the package in your frontend project:**

   In your frontend project directory, run:

   ```bash
   npm link @netlify/spark-ui
   ```

This will symlink your local `netlify-spark-ui` build into your frontend’s `node_modules`, allowing you to test changes without publishing a new package version.

### Testing Preact Components

When working with Preact components, keep in mind that changes to linked packages don’t automatically trigger a rebuild in consuming projects. You’ll need to manually rebuild Preact components.

```bash
npm run build:vite
```

If you’ve rebuilt but still don’t see updates in your frontend while running `npm run dev`, Vite’s cache may be serving stale modules. In that case, clear the `.vite` cache in your frontend project:

```bash
rm -rf node_modules/.vite
```

Then restart your dev server:

```bash
npm run dev
```

---

## AI-Assisted Page Building with Claude Code

This repo includes a [Claude Code](https://claude.ai/code) skill for generating landing pages using Spark UI components. The skill provides guidelines for correct component usage, layout utilities, and design tokens based on the Templates documentation.

### For contributors (working in this repo)

The skill is available automatically. Run:

```
/project:landing-page <describe the page you want>
```

For example:

```
/project:landing-page A landing page for a new enterprise hosting product with a hero, feature cards, and a pricing comparison
```

### For consumers (using spark-ui as a dependency)

If you're using `@netlify/spark-ui` in your own project, the skill guidelines are shipped with the package. Create a thin wrapper at `.claude/commands/landing-page.md` in your workspace root:

```markdown
# Create a Landing Page with Spark UI

$FILE node_modules/@netlify/spark-ui/skills/landing-page.md

## User Request

$ARGUMENTS
```

Then run `/project:landing-page` in Claude Code. The `$FILE` directive loads guidelines from your installed package — when you update `@netlify/spark-ui`, the prompt updates automatically.

> **Monorepo note:** Place `.claude/commands/` at the monorepo root, not inside a subdirectory like `apps/frontend/`.

---

## Remote Testing

When you’re ready to validate your component changes in a deploy preview, you can publish an **alpha release** and install it in your frontend project.

> ⚠️ You will need to make sure you're in the Netlify organization in NPM to have the right authorization to publish.
>
> Reach out to #internal-permissions in Slack

### Steps to Publish an Alpha Release:

1. **Make sure you're logged into npm locally**

   ```bash
   npm login
   ```

1. **Publish an alpha version of `netlify-spark-ui`:**

   ```bash
   npm publish --tag alpha
   ```

1. **Update the frontend’s `package.json` to use the alpha version:**

   ```json
   "@netlify/spark-ui": "1.0.0-alpha.0"
   ```

1. **Install the updated package:**
   ```bash
   npm install
   ```