---
applyTo: "**/*.scss,**/*.css"
---

# @cfx-dev/ui-components — SCSS Styling API

When your bundler is configured with `additionalData: '@use "ui" as ui;'`, the entire `ui.*` SCSS namespace is available in every `.scss` file without imports.

## Quant System (`ui.q()`)

The base unit is `--quant: calc(1rem * 0.25)`. All sizing uses quant multipliers:

```scss
.container {
  padding: ui.q(2);          // 0.5rem
  gap: ui.q(4);              // 1rem
  margin-top: ui.q(8);       // 2rem
  height: ui.q(10);          // 2.5rem
  border-width: ui.q(0.25);  // 1px equivalent
}
```

## Colors (`ui.color()`)

Theme-aware color function using CSS custom properties:

```scss
.element {
  // Basic color
  color: ui.color('primary');                    // rgba(var(--color-primary), 1)
  background: ui.color('bg');

  // With alpha
  color: ui.color('primary', $alpha: 0.5);       // 50% opacity
  border-color: ui.color('accent', $alpha: 0.2);

  // With luminance (50–950 scale, or 'pure' for base)
  color: ui.color('primary', 700);               // lighter shade
  background: ui.color('bg-light', 200, 0.5);    // shade + alpha
}
```

### Available Color Names

Theme colors: `accent`, `primary`, `secondary`, `tertiary`, `green`, `yellow`, `red`, `argentum`, `aurum`, `platinum`.
Background colors: `bg`, `bg-light`, `bg-dark`, `bg-dark-grey`, `bg-black`.
Luminance scale: `pure` (default), `50`, `100`, `200`, `300`, `400`, `500`, `600`, `700`, `800`, `900`, `950`.

## Color Tokens (`ui.color-token()`)

Named semantic tokens for component-specific colors:

```scss
.custom-button {
  color: ui.color-token('button-text');
  background: ui.color-token('button-background');

  &:hover {
    background: ui.color-token('button-hover-background');
  }
}

// Define custom tokens
@include ui.define-color-token('my-custom-bg', ui.color('accent', $alpha: 0.1));

.my-element {
  background: ui.color-token('my-custom-bg');
}
```

## CSS Custom Properties (`ui.def()` / `ui.use()`)

```scss
.component {
  @include ui.def('my-height', ui.q(10));       // --my-height: calc(var(--quant) * 10)
  height: ui.use('my-height');                    // var(--my-height, initial)
  max-height: ui.use('my-max-height', 100%);     // var(--my-max-height, 100%)
}
```

## Spacing & Offsets

```scss
.box {
  // Named offsets
  padding: ui.offset('normal');     // var(--offset-normal) = q(2)
  gap: ui.offset('large');          // var(--offset-large) = q(4)
  margin: ui.offset('small');       // var(--offset-small) = q(1)

  // Spacing tokens (numbered scale)
  padding: ui.spacing(200);         // mapped to global scale
  gap: ui.spacing(400);

  // Spacer (responsive named tokens)
  margin-bottom: ui.spacer('large');  // var(--spacer-large) — scales by breakpoint
}
```

### Offset Sizes

`none` (0), `hairthin` (1px), `thin` (2px), `xxsmall`, `xsmall`, `small`, `normal`, `medium`, `large`, `xlarge`, `safezone`.

## Typography

```scss
.heading {
  @include ui.font-family('secondary');     // HelveticaNowDisplay
  @include ui.font-size('xlarge');          // responsive font size token
  @include ui.font-weight('bold');          // 700
  @include ui.line-height('xlarge');
  @include ui.letter-spacing('large');
}

.body-text {
  font-size: ui.font-size('small');         // function form
  font-weight: ui.font-weight('regular');
  line-height: ui.line-height('small');
}
```

Font sizes: `xxxsmall`, `xxsmall`, `xsmall`, `small`, `medium`, `large`, `xlarge`, `xxlarge`, `xxxlarge`, `xxxxlarge`.
Font weights: `thin` (100), `small` (300), `regular` (400), `bold` (700), `bolder` (800), `boldest` (900).
Families: `primary` (HelveticaNowText), `secondary` (HelveticaNowDisplay).

## Border Radius

```scss
.card {
  @include ui.border-radius('medium');
  // or: border-radius: ui.border-radius('large');
}
```

Sizes: `none` (0), `xsmall`, `small`, `medium`, `large`, `xlarge`, `pill` (9999px).

## Control Heights

```scss
.my-control {
  height: ui.control-height('normal');   // q(6)
}
```

Sizes: `xxsmall`, `xsmall`, `small`, `normal`, `large`, `xlarge`, `xxlarge`.

## Responsive Media Queries

```scss
.container {
  padding: ui.q(2);

  @include ui.media-min('bp768') {
    padding: ui.q(4);
  }

  @include ui.media-min('bp1280') {
    padding: ui.q(6);
  }
}

// Max-width (mobile-first inverse)
@include ui.media-max('bp768') {
  .mobile-only { display: block; }
}
```

### Breakpoints

| Name | Width |
|------|-------|
| `initial` | 0px |
| `bp320` | 320px |
| `bp393` | 393px |
| `bp500` | 500px |
| `bp768` | 768px |
| `bp1024` | 1024px |
| `bp1280` | 1280px |
| `bp1440` | 1440px |
| `bp1920` | 1920px |
| `bp2560` | 2560px |

Legacy names (deprecated): `small` (360), `small-medium` (640), `medium` (1024), `medium-large` (1280), `large` (1920), `xlarge` (2560).

## Transitions

```scss
.button {
  @include ui.animated;                                    // all 0.25s ease
  @include ui.animated((background-color, color));         // specific props only
}
```

## Z-Index

```scss
.overlay {
  z-index: ui.zindex('max');          // 9000
  z-index: ui.zindex('flyout');       // 1000
  z-index: ui.zindex('select');       // 9099
  z-index: ui.zindex('title');        // 9100
}
```

Layers: `zero` (0), `first` (1), `second` (2), `flyout` (1000), `max` (9000), `select` (9099), `title` (9100).

## Viewport Functions

```scss
.full-viewport {
  width: ui.viewport-width();         // full viewport minus safezone
  height: ui.viewport-height(0.5);    // half viewport
}
```

## Negative Helper

```scss
.pull-up {
  margin-top: ui.negative(ui.q(2));  // calc(-1 * q(2))
}
```

## Placeholder Styling

```scss
.input {
  @include ui.placeholder-color(ui.color('secondary', $alpha: 0.4));
  @include ui.placeholder-animated('color');
}
```