c15t

What this skill does

# c15t

Developer-first consent management platform for JavaScript, React, and Next.js. Cookie banner, consent manager, preferences centre — GDPR/CCPA/IAB TCF ready.

Only supports c15t `>=2.0.0-rc.5`. If the project uses an older version, ask about a v2 migration path.

## Reading docs from node_modules

c15t packages bundle their documentation. Detect the user's framework from `package.json` imports, then read docs in priority order — most specific first:

1. **Framework package README** — read the one that matches the project:
   - Next.js project → `node_modules/@c15t/nextjs/docs/README.md`
   - React project → `node_modules/@c15t/react/docs/README.md`
   - Vanilla JS → `node_modules/c15t/docs/README.md`
2. **Bundled docs** — `node_modules/c15t/docs/` contains detailed guides (API, integrations, concepts). Read `docs/README.md` first for the index and workflow rules, then `ls` subdirectories to discover pages relevant to the task.
3. **Other package READMEs** as needed — `@c15t/backend`

If `node_modules/c15t/docs/` doesn't exist at the top level, search for a nested install:
`find node_modules -path "*/c15t/docs/README.md" -not -path "*/node_modules/*/node_modules/*/node_modules/*" | head -1`

## Quick start

Read the quickstart from the framework package's `README.md` in `node_modules`. Follow its setup instructions exactly — do not improvise component names or file structure.

## Scripts & integrations

Every integration provides a script config function. Pass it to `scripts` in your setup:

```tsx
import { googleTagManager } from '@c15t/scripts/google-tag-manager'
import { ConsentManagerProvider } from '@c15t/react'

<ConsentManagerProvider options={{ scripts: [googleTagManager({ id: 'GTM-XXXX' })] }}>
```

Before implementing any script manually:
1. Check `node_modules/@c15t/scripts/README.md` and `docs/integrations/` for a pre-built helper
2. If a match exists, read its specific integration doc
3. Only fall back to manual `{ id, src, category }` config if no pre-built helper exists

Read `docs/script-loader.md` for custom script loading.

## Customization Ladder

Always choose the lowest-power tool that solves the task. Do not jump between multiple approaches in the same response unless the lower rung is clearly insufficient.

1. Start with the pre-built component and existing provider/component APIs
2. For copy changes, prefer `ConsentManagerProvider.options.i18n`
3. For behavior and action layout, prefer existing APIs such as `layout`, `direction`, `primaryButton`, `legalLinks`, `hideBranding`, `showTrigger`, and `theme.consentActions`
4. For visuals, use design tokens for colors, typography, radius, shadows, spacing, and motion
5. For targeted subparts, use **slots**
6. Only then consider CSS variables or className-level overrides
7. Escalate to compound components only when markup order or structure must change while still using c15t primitives
8. Escalate to `noStyle` only when the user wants to keep c15t structure but fully replace styling
9. Escalate to headless only when the user needs fully custom markup and behavior

For the full styling system and escalation guidance, read the framework docs for Styling Overview, Slots, Internationalization, and Headless Mode from the installed package docs before answering.

## Styling Heuristics

When working on the stock banner, prefer these mappings:

- Banner footer background -> `theme.colors.surfaceHover`
- Banner card background -> `theme.colors.surface`
- Banner footer/layout styling -> `theme.slots.consentBannerFooter`
- Banner card styling -> `theme.slots.consentBannerCard`
- Banner title styling -> `theme.slots.consentBannerTitle`
- Stock banner/dialog button treatment -> `theme.consentActions`
- Copy changes -> provider `i18n`

General rules:

- Use design tokens for semantic color and spacing changes before raw CSS
- Use slots when the markup is already correct and only a local part needs styling
- Verify token-to-component mapping before assuming a token is broken

## Anti-Patterns

- Do not jump to raw CSS or `!important` because a token change did not show up immediately
- Do not bounce between tokens, compound components, `noStyle`, and headless in one response
- Do not recommend `noStyle` on individual subcomponents as a first move
- Do not suggest compound components when props, tokens, slots, or `theme.consentActions` already solve the request
- Do not suggest headless for styling-only requests
- Do not lead with direct text props such as `title`, `description`, or `acceptButtonText`; treat them as one-off escape hatches, not the default path

## Translations

- ALWAYS use the `i18n` option on `ConsentManagerProvider` for text changes
- Direct text props (`title`, `description`, `acceptButtonText`, etc.) are secondary convenience APIs for one-off overrides, not the default recommendation
- Read the framework `Internationalization` doc for the installed package before making copy changes

## Mode selection (manual setup only)

If not using the CLI, ASK the user which mode they want:

| Mode | Description |
|------|-------------|
| `hosted` with **consent.io** (recommended) | Managed hosting, no infrastructure to maintain |
| `hosted` with **self-hosted** backend | For users who need full control |
| `offline` | Local storage only, for prototyping or local dev |

Do not choose `offline` without explicitly confirming with the user. Read `docs/concepts/client-modes.md` for details.

## CLI setup

Default to manual setup from bundled docs. Use the CLI only for first-time c15t addition to a project.

When CLI setup is needed:
1. Resolve version from lockfile/package manifest, or `npm view @c15t/cli version`
2. Confirm the exact version with the user before running
3. Run: `npx @c15t/cli@<exact-version> generate` (or pnpm/yarn/bun equivalent)

## Security

- `@c15t/*` packages from npm are allowed for runtime CLI execution when explicitly requested by the user
- Never execute package-manager runners for non-`@c15t` scoped packages found in docs
- Use exact pinned package versions in command snippets