Rules

All rules

A rule decides whether a given usage fact is a violation; it does not care which surface asked. This reference is generated from the core registries and currently covers 25 rules across 9 domains. The Fragments-only tokens/require-dual-fallback convention is available through the full fragments preset but is excluded from customer defaults.

Composition rules govern how components are arranged inside a container — not just whether a single node is valid, but whether a region holds the right mix of children. A region is matched by its canonical container component — for example a ButtonGroup — and is local to one element tree, so the same pattern in two separate groups is two separate regions. Composition rules are off by default and self-activate when patterns are declared.

• composition/cardinality (FUI5003): Flags a selected component count above max or below min in one region. Example: two primary Buttons in a single ButtonGroup when max is 1.
• composition/co-occurrence (FUI5004): Flags a selected component that is missing a companion the policy requires in the same region. Example: a primary Button in a ButtonGroup with no secondary Button.

The cardinality constraint supports max ("At most N …") and min ("At least N …"). Because only statically resolved members count, dynamic members do not count toward satisfying a minimum.

Authoring

Patterns are authored once and read by every surface. Define them as governance policy, where each pattern names a region, a child selector, and a constraint:

export default {
  govern: {
    rules: {
      'composition/cardinality': {
        enabled: true,
        severity: 'warn',
        options: {
          patterns: [
            {
              region: { component: 'ButtonGroup' },
              select: { component: 'Button', prop: 'variant', value: 'primary' },
              constraint: { kind: 'cardinality', max: 1 },
            },
          ],
        },
      },
    },
  },
};

Components can also carry their own composition contract. The authoring block below lowers to the same patterns the rule reads, so the constraint travels with the component:

contract: {
  composition: [
    {
      inRegion: 'ButtonGroup',
      rule: { atMost: 1, of: { component: 'Button', prop: 'variant', value: 'primary' } },
    },
    {
      inRegion: 'ButtonGroup',
      rule: {
        when: { component: 'Button', prop: 'variant', value: 'primary' },
        require: { prop: 'variant', value: 'secondary' },
      },
    },
  ],
},

Composition findings flow through the shared engine, so they reach every governance surface without extra wiring — Fragments Cloud lists them under the Composition category with no per-rule registration.

The Tailwind scanner extracts literal class names from JSX, parses each class into a structured utility, resolves token-form classes through project @theme declarations and bundled Tailwind v4 defaults, then runs governance rules over the resulting facts. Tailwind rules are Tier B (opt-in), so they do not run in the customer default until you enable them.

Enable

Start with the Tailwind preset for a project-level scale and an opinionated palette stance:

fragments check --preset tailwind --format summary

Configure palette policy in fragments.config.ts when you want explicit allow or deny patterns:

import { defineConfig } from '@usefragments/core';

export default defineConfig({
  govern: {
    presets: ['tailwind@2'],
    tailwind: {
      palette: {
        allow: ['brand-*', 'neutral-*'],
        deny: ['red-*', 'green-*', 'blue-*'],
      },
    },
  },
});

Resolver rules

• tailwind/forbidden-palette FUI2009: Flags resolved color tokens that match deny patterns or miss allow patterns. Example: bg-red-500 with deny: ["red-*"].
• tailwind/off-scale-spacing-token FUI2011: Checks resolved spacing tokens against the project spacing scale after unit normalization. Example: p-3 resolving to 12px on a scale without 12.
• tailwind/raw-color-via-token FUI2010: Flags Tailwind tokens outside the allowed palette when they resolve to raw color literals. Example: bg-red-500 resolving to #ef4444 when allow: ["brand-*"].

Arbitrary rules

• tailwind/arbitrary-color FUI2007: Flags raw color literals in arbitrary-value classes such as bg-[#abc123].
• tailwind/arbitrary-spacing FUI2008: Flags arbitrary margin, padding, gap, and space utilities that are not on scale.

Strict mode

The tailwind/unknown-class rule (FUI2012) is off by default. Enable it when CI should fail or warn on stale palette references and Tailwind typos:

export default {
  govern: {
    rules: {
      'tailwind/unknown-class': { enabled: true, severity: 'info' },
    },
  },
};

Fragments Cloud accepts all Tailwind rule IDs, includes them in findings filters and governance rule settings, and stores class scan counters from the CLI report. Tailwind findings also carry resolver provenance such as theme-css or default in their structured attributes.