standards-ui

v1.34.0

Published

a month ago

A foundational design system built with native Web Components. Includes comprehensive TypeScript types, JSDoc documentation, and component examples.

0High
0Medium
0Low

jongrantwritescode

web-components design-system ui-components form-components standards accessible aria-compliant typescript jsdoc documentation testing performance

Design System - Web Components

🌐 View the Live Design System Site on GitHub Pages

A comprehensive design system built with native Web Components, featuring layout components and form elements with consistent styling and behavior.

Features

Native Web Components: Built using vanilla JavaScript and Web Components standards
Shadow DOM: Encapsulated styling with mode: 'open' for experimentation
CSS Custom Properties: Design tokens for consistent theming
Flexbox Layout: Responsive layout system with ds-row and ds-col
Form Components: Complete set of form elements with accessibility support
Customizable Design Tokens: Initialize with your own brand colors, spacing, and typography
Theme Switching: Dynamic theme switching with runtime token updates
TypeScript Support: Full TypeScript declarations for type safety
Storybook Integration: Interactive documentation and testing
JSDoc Documentation: Comprehensive API documentation
No Dependencies: Pure vanilla JavaScript implementation

Components

Layout Components

ds-page - Page container with consistent max-width and padding
ds-row - Flexbox row container with configurable alignment and spacing
ds-col - Flexbox column container with configurable growth and alignment

Form Components

ds-form - Form container with validation and accessibility support
ds-text-input - Text input with support for various input types
ds-button - Button component with variants and types
ds-radio - Radio button for single selection within groups
ds-checkbox - Checkbox for individual or grouped selections
ds-textarea - Multi-line text input
ds-select - Dropdown select with single/multiple selection
ds-option - Select option component
ds-label - Form label with association support
ds-fieldset - Form grouping container
ds-legend - Fieldset caption/title

Installation

npm install standards-ui

TypeScript Configuration

If you're using TypeScript, the library includes full type definitions. The JSX elements are automatically recognized by TypeScript when you import the library:

import { init } from "standards-ui";
import "standards-ui/styles.css";

All the custom web component elements like <ds-page>, <ds-button>, etc. are automatically recognized by TypeScript.

Quick Start

1. Initialize the Design System

import { init, DEFAULT_TOKENS } from "standards-ui";

// Initialize with default tokens
init(DEFAULT_TOKENS);

// Or customize with your own tokens
init({
  ...DEFAULT_TOKENS,
  color: {
    ...DEFAULT_TOKENS.color,
    primary: "#your-brand-color",
    secondary: "#your-secondary-color",
  },
  spacing: {
    ...DEFAULT_TOKENS.spacing,
    md: "20px",
  },
});

2. Use Components

Include the design system styles and components in your HTML:

<!DOCTYPE html>
<html lang="en">
  <head>
    <link rel="stylesheet" href="src/styles/styles.css" />
  </head>
  <body>
    <!-- Import components -->
    <script type="module" src="src/components/ds-page.js"></script>
    <script type="module" src="src/components/ds-row.js"></script>
    <script type="module" src="src/components/ds-col.js"></script>
    <script type="module" src="src/components/ds-text-input.js"></script>
    <!-- Import other components as needed -->

    <ds-page>
      <ds-row>
        <ds-col>
          <h1>My Application</h1>
        </ds-col>
      </ds-row>
    </ds-page>
  </body>
</html>

Listening to events

React

import React, { useEffect } from "react";
import { init } from "standards-ui";
import "standards-ui/styles.css";

// The JSX elements are automatically recognized by TypeScript

function App() {
  useEffect(() => {
    // Initialize the design system
    init();
  }, []);

  return (
    <ds-page>
      <ds-row>
        <ds-col>
          <ds-button>Click me</ds-button>
        </ds-col>
      </ds-row>
    </ds-page>
  );
}

Event Handling in React

import React, { useRef, useEffect } from "react";

function FormExample() {
  const inputRef = useRef(null);

  useEffect(() => {
    const input = inputRef.current;
    if (input) {
      const handleChange = (e) => {
        console.log("Value changed:", e.detail.value);
      };

      input.addEventListener("ds-change", handleChange);
      return () => input.removeEventListener("ds-change", handleChange);
    }
  }, []);

  return <ds-text-input ref={inputRef} placeholder="Enter text..." />;
}

TypeScript Support

The library includes full TypeScript support:

JSX elements are automatically recognized by TypeScript
All component props are properly typed
No additional type imports needed

Angular

<ds-text-input
  (input)="onInput($event)"
  (change)="onChange($event)"
  (ds-change)="onDsChange($event)"></ds-text-input>

Vue

<ds-text-input @input="onInput" @change="onChange" @ds-change="onDsChange" />

Svelte

<ds-text-input
  on:input="{onInput}"
  on:change="{onChange}"
  on:ds-change="{onDsChange}" />

Testing

🧪 Zero-configuration Jest testing with true JSDOM compatibility!

Jest Setup Guide: Complete copy-paste setup for Jest tests
Testing Utilities Guide: Comprehensive testing documentation

Quick Jest Setup:

import { setupTesting } from "standards-ui/testing";
beforeAll(async () => await setupTesting());
// Now all ds-* components work perfectly in Jest/JSDOM!

Documentation

Live Site (Landing Page): Main entry point for the design system
Storybook: Interactive component documentation and testing
Storybook: Interactive component examples and documentation
JSDoc Documentation: Comprehensive API documentation
Additional Markdown Docs: Extra documentation (local repo only)

Design Tokens

The design system uses CSS custom properties for consistent theming:

Browser Support

Chrome 67+
Firefox 63+
Safari 10.1+
Edge 79+

Development

Project Structure

ai_design_system/
├── src/                     # Source code and components
│   ├── components/          # Web Components
│   ├── design_system/       # Design tokens and base styles
│   └── stories/             # Storybook stories
├── docs/                    # Documentation
├── plans/                   # Development plans and specifications
├── tests/                   # Test files

├── .storybook/              # Storybook configuration
├── .github/                 # GitHub workflows and templates
├── docs-output/             # JSDoc documentation output
├── storybook-static/        # Built Storybook files
├── node_modules/            # Dependencies
└── README.md

Available Scripts

npm start: Start development server
npm run storybook: Start Storybook
npm run build-storybook: Build Storybook for production
npm run generate-docs: Generate JSDoc documentation
npm run serve-docs: Generate docs and serve locally
npm test: Run tests (if configured)

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

License

This project is licensed under the MIT License.