@sky.ui/utils

JIT utility CSS for Sky UI: PostCSS plugin, Vite integration, browser runtime, Prettier plugin, and a suggestion engine for editor tooling.

Install

npm install "@sky.ui/utils" postcss

Quote scoped names ("@sky.ui/…") — required in PowerShell. See powershell-scoped-packages.md.

Optional peers: vite (for @sky.ui/utils/vite), prettier ≥ 3 (for @sky.ui/utils/prettier-plugin).

Quick start

Add @skyui utilities once in global CSS, then use utility classes in markup:

@skyui utilities;

<div class="flex gap-4 p-4 rounded-lg bg-primary-500">Hello</div>

Configure scanning and theme in skyui.config.js at the project root (loaded automatically when present).

PostCSS

import skyUIPostcss from '@sky.ui/utils';

export default {
  plugins: [
    skyUIPostcss({
      content: ['./**/*.{html,vue,tsx,jsx}'],
      // outLog: true,           // @apply warnings in the terminal
      // scanDiagnostics: true,  // result.skyuiScanDiagnostics
    }),
  ],
};

JS config plugins

// skyui.config.js
export default {
  plugins: [
    ({ addUtilities, addComponents, addBase }) => {
      addUtilities({ '.btn-plugin': { padding: '0.5rem 1rem' } });
    },
  ],
};

Or in CSS:

@skyui plugin "./plugins/my-sky-plugin.js";
@skyui utilities;

| Plugin API | Notes | |------------|-------| | addUtilities / addComponents / addBase | Object, array, or string; nested &:hover, @media, multi-selector keys | | matchUtilities / matchComponents | Theme-keyed generators (values: theme('spacing')) | | addVariant | Custom variant prefixes | | config({ theme }) | Merge theme during plugin run | | theme('colors.primary') | Dot-path into merged theme | | Built-in plugins | @skyui plugin "@skyuicss/forms", @skyuicss/typography, @skyuicss/container-queries |

Vite

import { SkyUIUtilsVitePlugin } from '@sky.ui/utils/vite';

export default {
  plugins: [SkyUIUtilsVitePlugin()],
};

Defaults scan index.html and {app,src,components}/**/*.{js,ts,jsx,tsx,vue,html,mdx} unless you pass content.

Prettier (class sorting)

// prettier.config.js
export default {
  plugins: ['@sky.ui/utils/prettier-plugin'],
};

Sorts utilities in class, className, and @apply.

CSS directives

@skyui source

@skyui source "../src/**/*.vue";
@skyui source inline("hidden animate-spin");
@skyui utilities;

@skyui theme

@skyui theme {
  --color-brand: #0066cc;
  --spacing-huge: 9rem;
}
@skyui utilities;

@skyui reference (Vue SFC / scoped styles)

When global CSS already includes @skyui utilities:

@skyui reference;
.card { @apply rounded-lg p-4 shadow-md; }

@skyui utility and @skyui variant

@skyui utility tab-4 { tab-size: 4; }
@skyui variant hocus (&:hover, &:focus-visible);
@skyui utilities;

Content scanning

The PostCSS plugin resolves relative imports when scanning (e.g. :class="ROW" where ROW is imported from ./styles).

Supported patterns include static class / className, :class arrays and objects, :class="CONST" from script constants, cn / clsx / cva, and JSX template literals with static segments.

Browser runtime

<script src="node_modules/@sky.ui/utils/dist/sky-ui.runtime.js"></script>

skyui.run() scans the DOM and injects JIT CSS using the same extraction heuristics as PostCSS.

Suggestion engine

import { getCompletions, getClassCatalog } from '@sky.ui/utils/suggestion-engine';

Used by the Sky UI IntelliSense VS Code extension and available for custom tooling.

Editor support

Fix “Unknown at rule” for @apply / @skyui

1. Sky UI IntelliSense extension (recommended) — completions for utilities, @apply, @skyui, @layer, and skyui.config.
2. Workspace settings — point CSS custom data at the published file:

{
  "css.customData": ["./node_modules/@sky.ui/utils/skyui.css-data.json"],
  "scss.customData": ["./node_modules/@sky.ui/utils/skyui.css-data.json"],
  "less.customData": ["./node_modules/@sky.ui/utils/skyui.css-data.json"]
}

Also available as @sky.ui/utils/css-data.

Debugging missing classes

1. Include @skyui utilities once in global CSS.
2. Widen content in skyui.config.js or add @skyui source.
3. Clear .cache/.skyui-cache.json if the file list looks stale.
4. Use safelist for runtime-only dynamic class names.
5. Enable scanDiagnostics: true on the PostCSS plugin for structured scan output.

Related packages

| Package | Description | |---------|-------------| | @sky.ui/core | Web components | | @sky.ui/mcp | MCP server for AI-assisted Sky UI development |

License

Sky UI Free EULA — proprietary; not open source.