@vibe-labs/design-components-lists

List component tokens, styles, and TypeScript types for the Vibe Design System.

Installation

bash

npm install @vibe-labs/design-components-lists

css

@import "@vibe-labs/design-components-lists";

import { ListVariants, ListSizes } from "@vibe-labs/design-components-lists/types";
import type { ListStyleProps, ListItemStyleProps } from "@vibe-labs/design-components-lists/types";

Tokens

CSS custom properties defined in @layer vibe.tokens (file: lists.css).

Container

Token	Default
`--list-bg`	`--surface-base`
`--list-border-color`	`--border-subtle`
`--list-border-width`	`--border-width-1`
`--list-radius`	`--radius-lg`
`--list-padding`	`--space-1`
`--list-gap`	`0`

Item

Token	Default	Description
`--list-item-height-sm`	`2rem`	Small item height
`--list-item-height-md`	`2.5rem`	Medium item height
`--list-item-height-lg`	`3rem`	Large item height
`--list-item-px`	`--space-3`	Horizontal padding
`--list-item-gap`	`--space-3`	Internal gap
`--list-item-radius`	`--radius-md`	Item corner radius
`--list-item-font-size-sm`	`--text-xs`	Small font size
`--list-item-font-size-md`	`--text-sm`	Medium font size
`--list-item-font-size-lg`	`--text-base`	Large font size
`--list-item-color`	`--text-primary`	Text color
`--list-item-bg`	`transparent`	Default background
`--list-item-hover-bg`	`--surface-hover-overlay`	Hover background
`--list-item-active-bg`	`--surface-active-overlay`	Active/press bg
`--list-item-disabled-opacity`	`--input-disabled-opacity`	Disabled opacity

Selection

Token	Default
`--list-item-selected-bg`	accent @ 8% mix
`--list-item-selected-color`	`--text-primary`
`--list-item-selected-indicator`	`--color-accent`
`--list-item-selected-indicator-width`	`3px`

Divider

Token	Default
`--list-divider-color`	`--border-subtle`
`--list-divider-indent`	`0`

Icon

Token	Default
`--list-icon-size`	`1.125rem`
`--list-icon-color`	`--text-muted`
`--list-icon-active-color`	`--color-accent`

Description

Token	Default
`--list-description-font-size`	`--text-xs`
`--list-description-color`	`--text-muted`

Trail

Token	Default
`--list-trail-color`	`--text-muted`
`--list-trail-font-size`	`--text-xs`

Group

Token	Default
`--list-group-label-font-size`	`--text-xs`
`--list-group-label-color`	`--text-muted`
`--list-group-label-font-weight`	`--font-semibold`
`--list-group-label-px`	`--space-3`
`--list-group-label-py`	`--space-2`

Empty State

Token	Default
`--list-empty-py`	`--space-8`
`--list-empty-color`	`--text-muted`
`--list-empty-font-size`	`--text-sm`

Drag / Reorder

Token	Default
`--list-handle-color`	`--text-muted`
`--list-handle-hover-color`	`--text-secondary`
`--list-handle-size`	`1rem`
`--list-dragging-opacity`	`0.5`
`--list-dragging-shadow`	`--shadow-lg`
`--list-drop-indicator-color`	`--color-accent`
`--list-drop-indicator-height`	`2px`

Stripe

Token	Default
`--list-stripe-bg`	`--surface-subtle`

Generated Styles

Component classes generated into @layer vibe.components (file: lists.g.css).

Variants

Variant	Description
`default`	Surface base bg, subtle border
`outlined`	Transparent bg, stronger border
`elevated`	Elevated surface bg, drop shadow, no border
`ghost`	No bg, no border, no padding

Sizes

Set on container, cascades to items.

Size	Min-height	Font size
`sm`	`2rem`	`text-xs`
`md`	`2.5rem`	`text-sm`
`lg`	`3rem`	`text-base`

Item

Flex row with gap for icon, content, and trail. Supports data-selected, data-disabled, data-dragging, and data-drag-over states. Focus ring via focus-visible. Selected items show a left accent indicator via inset box-shadow.

Item Slots

Class	Description
`.list-item-icon`	Leading icon, accent-colored when selected
`.list-item-content`	Flex column wrapper for label + description
`.list-item-label`	Primary text, truncated with ellipsis
`.list-item-description`	Secondary text, smaller + muted
`.list-item-trail`	Trailing slot (actions, meta), auto-pushed right
`.list-item-handle`	Drag grip, grab cursor, `touch-action: none`

Container Flags

Flag	Description
`data-divided`	Auto-inserts border-top between adjacent items
`data-striped`	Alternating row backgrounds on even items
`data-hoverable`	Hover bg transition on items
`data-interactive`	Pointer cursor + active press bg on items
`data-flush`	Strips all container chrome (bg, border, radius, padding)
`data-reorderable`	Enables drag/drop states (dragging opacity/shadow, drop indicator)

TypeScript Types

ListVariants    // ["default", "outlined", "elevated", "ghost"]
ListSizes       // ["sm", "md", "lg"]

type ListVariant
type ListSize

interface ListStyleProps {
  variant?: ListVariant;
  size?: ListSize;
  divided?: boolean;
  striped?: boolean;
  hoverable?: boolean;
  interactive?: boolean;
  flush?: boolean;
  reorderable?: boolean;
}

interface ListItemStyleProps {
  selected?: boolean;
  disabled?: boolean;
  dragging?: boolean;
  dragOver?: boolean;
}

interface ListItemIconStyleProps {}
interface ListItemContentStyleProps {}
interface ListItemLabelStyleProps {}
interface ListItemDescriptionStyleProps {}
interface ListItemTrailStyleProps {}
interface ListItemHandleStyleProps {}
interface ListGroupStyleProps {}
interface ListGroupLabelStyleProps {}
interface ListDividerStyleProps {}
interface ListEmptyStyleProps {}

Dist Structure

File	Description
`index.css`	Barrel — imports tokens + generated styles
`lists.css`	Token definitions
`lists.g.css`	Generated component styles
`index.js` / `index.d.ts`	TypeScript types + runtime constants

Dependencies

Requires tokens from @vibe-labs/design (colors, surfaces, borders, spacing, typography, transitions, elevation).

Build

bash

npm run build

Usage Guide

Import

css

@import "@vibe-labs/design-components-lists";

import type { ListStyleProps, ListItemStyleProps } from "@vibe-labs/design-components-lists/types";

Variants

Variant

Set data-variant on .list: default · outlined · elevated · ghost

Size

Set data-size on .list: sm · md (default) · lg

Item states

Set on .list-item: data-selected · data-disabled · data-dragging · data-drag-over

Container flags

data-divided — borders between items
data-striped — alternating row backgrounds
data-hoverable — hover background on items
data-interactive — pointer cursor + active press state
data-flush — removes container chrome
data-reorderable — enables drag/drop visual states

Examples

Simple list

html

<!-- Default list with standard items -->
<ul class="list" role="list">
  <li class="list-item">Item one</li>
  <li class="list-item">Item two</li>
  <li class="list-item">Item three</li>
</ul>

List with icons, labels, descriptions, and trailing content

html

<ul class="list" data-variant="default" data-divided>
  <li class="list-item">
    <span class="list-item-icon">
      <svg><!-- icon --></svg>
    </span>
    <div class="list-item-content">
      <span class="list-item-label">Design System</span>
      <span class="list-item-description">CSS tokens, components, and Vue bindings</span>
    </div>
    <span class="list-item-trail">
      <span class="badge" data-variant="success-subtle" data-size="sm">Active</span>
    </span>
  </li>
  <li class="list-item">
    <span class="list-item-icon">
      <svg><!-- icon --></svg>
    </span>
    <div class="list-item-content">
      <span class="list-item-label">Analytics</span>
      <span class="list-item-description">Usage metrics and reporting</span>
    </div>
    <span class="list-item-trail">
      <span class="badge" data-variant="warning-subtle" data-size="sm">Beta</span>
    </span>
  </li>
</ul>

Interactive selectable list

html

<!-- Interactive list — items respond to click with cursor and active state -->
<ul class="list" data-interactive data-hoverable>
  <li class="list-item" data-selected>
    <div class="list-item-content">
      <span class="list-item-label">Selected item</span>
    </div>
  </li>
  <li class="list-item">
    <div class="list-item-content">
      <span class="list-item-label">Normal item</span>
    </div>
  </li>
  <li class="list-item" data-disabled>
    <div class="list-item-content">
      <span class="list-item-label">Disabled item</span>
    </div>
  </li>
</ul>

Grouped list with section labels

html

<ul class="list" data-variant="outlined">
  <li class="list-group">
    <div class="list-group-label">Pinned</div>
    <ul>
      <li class="list-item"><span class="list-item-label">Dashboard</span></li>
    </ul>
  </li>
  <li class="list-divider"></li>
  <li class="list-group">
    <div class="list-group-label">Recent</div>
    <ul>
      <li class="list-item"><span class="list-item-label">Project Alpha</span></li>
      <li class="list-item"><span class="list-item-label">Project Beta</span></li>
    </ul>
  </li>
</ul>

Reorderable list with drag handles

html

<ul class="list" data-reorderable data-hoverable>
  <li class="list-item">
    <span class="list-item-handle" aria-hidden="true">
      <svg><!-- drag grip icon --></svg>
    </span>
    <div class="list-item-content">
      <span class="list-item-label">Drag me</span>
    </div>
  </li>
  <!-- .list-item[data-dragging] and .list-item[data-drag-over] are set by JS -->
</ul>

Empty state

html

<ul class="list">
  <li class="list-empty">No items found.</li>
</ul>

With Vue

Use @vibe-labs/design-vue-lists for <SbList>, <SbListItem>, <SbListGroup>, and <SbListEmpty> components that accept ListStyleProps and ListItemStyleProps and handle drag-and-drop integration.

@vibe-labs/design-components-lists ​

Installation ​

Contents ​

Tokens ​

Container ​

Item ​

Selection ​

Divider ​

Icon ​

Description ​

Trail ​

Group ​

Empty State ​

Drag / Reorder ​

Stripe ​

Generated Styles ​

Variants ​

Sizes ​

Item ​

Item Slots ​

Container Flags ​

TypeScript Types ​

Dist Structure ​

Dependencies ​

Build ​

Usage Guide ​

Import ​

Variants ​

Variant ​

Size ​

Item states ​

Container flags ​

Examples ​

Simple list ​

List with icons, labels, descriptions, and trailing content ​

Interactive selectable list ​

Grouped list with section labels ​

Reorderable list with drag handles ​

Empty state ​

With Vue ​

@vibe-labs/design-components-lists

Installation

Contents

Tokens

Container

Item

Selection

Divider

Icon

Description

Trail

Group

Empty State

Drag / Reorder

Stripe

Generated Styles

Variants

Sizes

Item

Item Slots

Container Flags

TypeScript Types

Dist Structure

Dependencies

Build

Usage Guide

Import

Variants

Variant

Size

Item states

Container flags

Examples

Simple list

List with icons, labels, descriptions, and trailing content

Interactive selectable list

Grouped list with section labels

Reorderable list with drag handles

Empty state

With Vue