@ics-public/styles

v0.0.3

Published

a month ago

ICS UI core styles and Tailwind plugin

0High
0Medium
0Low

@ics-public/styles

The core ICS Design System styles package containing CSS files for components, themes, and utilities. Built with Tailwind CSS v4 and provides TypeScript variant types for component styling. Framework-agnostic and works with any Vue/React/framework setup.

Installation

npm install @ics-public/styles
# or
pnpm add @ics-public/styles
# or
yarn add @ics-public/styles

Usage

Basic Setup

Import the ICS Design System styles in your main CSS file:

@import "@ics-public/styles";

This will import:

Tailwind CSS base styles
ICS component styles
ICS utilities
Default theme variables
Animation utilities from tw-animate-css

Package Structure

The package exports CSS files organized into:

@ics-public/styles/
├── index.css          # Main entry point
├── base/              # Base styles and CSS variables
│   └── base.css       # Layout tokens, typography, scrollbar
├── components/        # Component-specific styles
│   ├── avatar.css
│   ├── button.css
│   ├── modal.css
│   ├── surface.css
│   ├── switch.css
│   ├── tabs.css
│   ├── tag.css
│   └── index.css
├── themes/            # Theme definitions
│   ├── default/       # Default theme
│   │   ├── index.css  # Theme entry point
│   │   └── variables.css  # Theme variables (light/dark)
│   └── shared/        # Shared theme utilities
│       └── theme.css  # Calculated variables and utilities
└── utilities/         # Utility classes
    └── index.css

Importing Specific Components

Instead of importing everything, you can import only what you need:

/* Import Tailwind CSS base */
@import "tailwindcss";

/* Import only specific components */
@import "@ics-public/styles/components/button.css" layer(components);
@import "@ics-public/styles/components/avatar.css" layer(components);

/* Import theme */
@import "@ics-public/styles/themes/default" layer(base);

Component Classes

Components use a BEM-like naming convention:

Base: .button
Variants: .button--primary, .button--danger
Sizes: .button--sm, .button--lg
Modifiers: .button--icon-only

Button Example

<!-- Basic button -->
<button class="button">Click me</button>

<!-- Primary variant -->
<button class="button button--primary">Save</button>

<!-- Small size -->
<button class="button button--sm">Small</button>

<!-- Icon-only button -->
<button class="button button--icon-only">
  <svg>...</svg>
</button>

<!-- Combining classes -->
<button class="button button--primary button--sm">Small Primary</button>

Themes

The default theme provides automatic light/dark mode support:

Light mode: Applied by default to :root
Dark mode: Applied with .dark class or [data-theme="dark"] attribute

<!-- Dark mode with class -->
<html class="dark">
  <!-- Dark mode with data attribute -->
  <html data-theme="dark"></html>
</html>

TypeScript Variant Types

All components export TypeScript types for IDE autocomplete and type safety:

import type {
  ButtonVariants,
  AvatarVariants,
} from "@ics-public/styles/components/button";
import type { AvatarVariants } from "@ics-public/styles/components/avatar";

// Get type definitions for component variants
type ButtonProps = ButtonVariants;

// Example usage with type checking
const buttonClass = {
  size: "lg" as const,
  variant: "primary" as const,
};

Available Component Types

ButtonVariants — from @ics-public/styles/components/button
AvatarVariants — from @ics-public/styles/components/avatar

These types provide IDE autocomplete for all variant options when developing with TypeScript.

CSS Variables

The package provides a comprehensive set of CSS variables for customization:

Layout Tokens

:root {
  /* Spacing */
  --spacing: 0.25rem;

  /* Border */
  --border-width: 0px; /* no border by default */
  --field-border-width: var(--border-width);
  --disabled-opacity: 0.5;

  /* Radius */
  --radius: 0.5rem;
  --field-radius: calc(var(--radius) * 1.5);

  /* Ring offset - Used for focus ring */
  --ring-offset-width: 2px;

  /* Cursor */
  --cursor-interactive: pointer;
  --cursor-disabled: not-allowed;
}

Theme Colors

:root {
  /* Primitive Colors (Do not change between light and dark) */
  --white: oklch(100% 0 0);
  --black: oklch(0% 0 0);
  --snow: oklch(0.9911 0 0);
  --eclipse: oklch(0.2103 0.0059 285.89);

  /* Base Colors */
  --background: oklch(0.9702 0 0);
  --foreground: var(--eclipse);

  /* Surface: Used for non-overlay components (cards, accordions, disclosure groups) */
  --surface: var(--white);
  --surface-foreground: var(--foreground);

  /* Overlay: Used for floating/overlay components (tooltips, popovers, modals, menus) */
  --overlay: var(--white);
  --overlay-foreground: var(--foreground);

  --muted: oklch(0.5517 0.0138 285.94);
  --scrollbar: oklch(87.1% 0.006 286.286);

  --default: oklch(94% 0.001 286.375);
  --default-foreground: var(--eclipse);

  /* Interactive Colors */
  --accent: oklch(0.6204 0.195 253.83);
  --accent-foreground: var(--snow);

  /* Status Colors */
  --success: oklch(0.7329 0.1935 150.81);
  --success-foreground: var(--eclipse);

  --warning: oklch(0.7819 0.1585 72.33);
  --warning-foreground: var(--eclipse);

  --danger: oklch(0.6532 0.2328 25.74);
  --danger-foreground: var(--snow);

  /* Component Colors */
  --segment: var(--white);
  --segment-foreground: var(--eclipse);

  /* UI Colors */
  --border: oklch(0 0 0 / 0%);
  --separator: oklch(92% 0.004 286.32);
  --focus: var(--accent);
  --link: var(--foreground);

  /* Shadows */
  --surface-shadow: 0 2px 4px 0 rgba(0, 0, 0, 0.04), 0 1px 2px 0 rgba(0, 0, 0, 0.06),
    0 0 1px 0 rgba(0, 0, 0, 0.06);
  --overlay-shadow: 0 4px 16px 0 rgba(24, 24, 27, 0.08), 0 8px 24px 0 rgba(24, 24, 27, 0.09);
  --field-shadow: 0 2px 4px 0 rgba(0, 0, 0, 0.04), 0 1px 2px 0 rgba(0, 0, 0, 0.06),
    0 0 1px 0 rgba(0, 0, 0, 0.06);
}

Note: Dark mode overrides specific variables (like --background, --surface, --overlay, --muted, --scrollbar, --default, --warning, --danger, --segment, --separator, and shadow values) when .dark class or [data-theme="dark"] attribute is applied.

Field Tokens

:root {
  /* Form field defaults */
  --field-background: var(--white);
  --field-foreground: oklch(0.2103 0.0059 285.89);
  --field-placeholder: var(--muted);
  --field-border: transparent; /* no border by default on form fields */
  --field-border-width: var(--border-width);
  --field-radius: calc(var(--radius) * 1.5);
}

Providing any of these knobs automatically updates the generated utilities (bg-field, placeholder:text-field-placeholder, rounded-field, etc.) along with the calculated hover/focus variants.

Calculated Variables

The theme also provides calculated variables for hover states, soft colors, and surface levels (defined in themes/shared/theme.css):

Hover states: --color-accent-hover, --color-success-hover, --color-warning-hover, --color-danger-hover, --color-default-hover
Soft colors: --color-accent-soft, --color-danger-soft, --color-warning-soft, --color-success-soft (with their foreground and hover variants)
Surface levels: --color-surface-secondary, --color-surface-tertiary
Radius scale: --radius-xs through --radius-4xl (calculated from --radius)
Transition timing functions: Various easing curves like --ease-smooth, --ease-out-fuild, etc.

Dependencies

Tailwind CSS v4+: Required peer dependency for styling
tailwind-variants: Used for component variant system
tw-animate-css: Provides animation utilities
tailwind-merge: Utility for merging Tailwind classes

Build Output

The package provides:

dist/index.css: Main unminified CSS file
dist/index.js: JavaScript bundle with Tailwind variant exports
dist/index.d.ts: TypeScript type definitions for variants
dist/components/*/index.d.ts: Component-specific type definitions

Framework Integration

This package is designed to work with any framework. Import the styles and use the exported TypeScript types for variant definitions:

Vue 3: Import styles and component types
React: Import styles and component types
Any other framework: Import CSS and TypeScript types as needed

Troubleshooting

IDE not showing variant suggestions

Make sure to:

Install the latest version: pnpm install
Verify package.json exports point to dist/ folder (not src/)

Update tsconfig.json with proper module resolution:

{
  "compilerOptions": {
    "moduleResolution": "bundler",
    "skipLibCheck": false
  }
}

Import directly from component exports: import type { ButtonVariants } from "@ics-public/styles/components/button"

License

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@ics-public/styles

Installation

Usage

Basic Setup

Package Structure

Importing Specific Components

Component Classes

Button Example

Themes

TypeScript Variant Types

Available Component Types

CSS Variables

Layout Tokens

Theme Colors

Field Tokens

Calculated Variables

Dependencies

Build Output

Framework Integration

Troubleshooting

IDE not showing variant suggestions

License