JavaScript Derivatives - Seventh UI CSS

Package Boundary

@seventh-ui/css is the canonical visual package. It owns tokens, reset/base styles, layout helpers, component CSS, icons, illustrations, static markup examples, and CSS entrypoints.

Runtime packages must be separate npm packages and separate repositories. They should import or peer-depend on @seventh-ui/css and add behavior without rewriting the CSS contract.

Planned Package Family

Package	Role	Relationship to CSS
`@seventh-ui/css`	Visual contract, assets, and docs.	Source package. No runtime dependency.
`@seventh-ui/jsvanilla`	Reference behavior for plain HTML and legacy migrations.	Depends on `@seventh-ui/css` and attaches behavior through documented hooks.
`@seventh-ui/react`	React components with idiomatic props, state, refs, and events.	Depends on `@seventh-ui/css`; should not require the vanilla runtime.
`@seventh-ui/vuejs`	Vue components with idiomatic props, emits, slots, and v-model support.	Depends on `@seventh-ui/css`; follows the same markup and state semantics.
`@seventh-ui/angular`	Angular components, directives, forms integration, and services.	Depends on `@seventh-ui/css`; maps CSS states to Angular APIs.
`@seventh-ui/quasar`	Optional Quasar adapter or component wrappers when native Quasar APIs need DS styling.	Depends on `@seventh-ui/css`; must avoid overriding Quasar layout behavior globally.

Markup Contract

Preserve classes

Render the documented .sui-* root, element, and modifier classes. Framework wrappers may add classes, but should not rename public CSS classes.

Use semantic HTML

Prefer native controls for form components. Do not replace native inputs with ARIA-only widgets unless the component requires a composite interaction.

Keep slots stable

Respect documented element slots such as header, body, footer, leading icon, trailing action, panel, item, and label.

Do not style by hooks

data-sui-* attributes are runtime hooks. Visual styling should remain driven by classes, native state, ARIA state, and CSS variables.

Runtime Hook Conventions

Derivative packages should use prefixed hooks when they need DOM discovery in plain HTML. Framework packages may expose props instead, but the rendered semantics should remain equivalent.

<button
  class="sui-btn sui-btn--primary"
  type="button"
  data-sui-trigger="dialog"
  data-sui-target="#delete-dialog">
  Open dialog
</button>

<section
  class="sui-dialog sui-dialog--medium"
  id="delete-dialog"
  role="dialog"
  aria-modal="true"
  aria-labelledby="delete-dialog-title"
  data-sui-component="dialog"
  data-sui-state="closed">
  ...
</section>

Hook	Use
`data-sui-component`	Optional root hook, for example `dialog`, `tabs`, `toast`, or `menu`.
`data-sui-trigger`	Element that opens, closes, toggles, selects, dismisses, or controls a component.
`data-sui-target`	Selector or id reference controlled by a trigger.
`data-sui-state`	Runtime state when native state or ARIA is not enough.
`data-sui-value`	Stable value for selections, tabs, menu items, slider helpers, or emitted events.

State Rules

Use the narrowest state mechanism that matches the platform. Native state and ARIA should be preferred because they are visible to assistive technology and CSS selectors.

disabled
checked
open
aria-expanded="true"
aria-selected="true"
aria-current="page"
aria-invalid="true"
aria-hidden="true"
.sui-component--modifier
--sui-component-value: 50%;

Behavior Matrix

Component	CSS package supports	Derivative package owns
Button, Input	Native element styling, sizes, variants, disabled/focus/error states.	Async loading policy, masks, validation orchestration, and form integration beyond native behavior.
Checkbox, Radio, Switch, Segmented Button	Native input styling and selected/disabled/focus states.	Controlled state APIs, indeterminate assignment, grouped validation, and framework form bindings.
Tooltip	Surface, arrow positions, light/dark themes, rich content layout.	Visibility timing, hover/focus triggers, Escape behavior, portal strategy, and collision handling.
Toast	Toast surfaces, status variants, region layout, close affordance, and 6000ms timing contract.	Queueing, auto-dismiss, pause on hover/focus, announcements, and removal lifecycle.
Dialog	Scrim, dialog sizes, header/body/footer layout, responsive actions, dark theme.	Open/close state, focus trap, Escape handling, inert background, native dialog fallback, and return focus.
Tabs, Menu, Navigation	Visual states, item layout, selected/current styling, panels, drawers, and surfaces.	Keyboard navigation, roving tabindex, route binding, open/close state, typeahead, and nested interaction rules.
Slider	Native range styling, fill variables, range visual hooks, size and state variants.	Value synchronization, lower/upper collision rules, formatted labels, active handle order, and ARIA values.
People Picker, Data Table	Static layout, item states, chips/tags, selectable rows, toolbar, filters, and pagination surfaces.	Search, async loading, selection state, sorting, filtering, pagination, expansion, virtualization, and data fetching.

Suggested Vanilla Events

The future vanilla package should use bubbling DOM CustomEvent events with a sui: prefix. Framework packages may expose idiomatic APIs, but should map to the same semantic actions.

sui:dialog:before-open
sui:dialog:open
sui:dialog:before-close
sui:dialog:close
sui:tabs:change
sui:menu:select
sui:toast:show
sui:toast:dismiss
sui:data-table:sort
sui:data-table:page-change

Accessibility Requirements

Derivative packages must target WCAG 2.2 AA where applicable and must not rely on visual CSS state alone. Composite widgets need keyboard behavior, focus management, labels, announcements, and disabled semantics.

At minimum, validate Tab and Shift+Tab order, Escape behavior for dismissible overlays, arrow-key behavior for tabs and menus, screen reader names/descriptions, reduced motion, and focus return after closing overlays.

Version Alignment

Derivative packages should align their major version with @seventh-ui/css and declare a peer dependency on the matching CSS major.

{
  "peerDependencies": {
    "@seventh-ui/css": "^1.0.0"
  }
}