CTT Web Components

A modern web components library for CTT built with Lit and TypeScript. This library provides reusable UI components following the CTT design system, with comprehensive documentation and testing via Storybook.

🚀 Features

• Modern Web Components: Built with Lit framework for excellent performance and compatibility
• TypeScript Support: Full TypeScript support with type definitions
• Design System: Consistent design tokens and styling
• Storybook Integration: Interactive component documentation and testing
• Accessibility: Built with accessibility best practices
• Testing: Comprehensive test coverage with Vitest and Playwright

🌐 Live Documentation

📚 Storybook: https://ctt-design-system-storybook.netlify.app

Browse and interact with all components, view documentation, and test different states in our live Storybook deployment.

📦 Installation

npm install ctt-web-components

🛠️ Development

Prerequisites

• Node.js (v18 or higher)
• npm

Getting Started

1. Clone the repository

   git clone https://github.com/ctt/pt.dni.design-system.git
   cd pt.dni.design-system

2. Install dependencies

   The project requires installing dependencies for both the core library and the Storybook environment.

   # Install core dependencies
   npm install
   
   # Install Storybook dependencies
   cd src/storybook
   npm install
   cd ../..

3. Start development server

   npm run dev

4. Start Storybook

   npm run storybook

Available Scripts

| Command | Description | | -------------------------- | ---------------------------------- | | npm run dev | Start development server | | npm run build | Build for production | | npm run preview | Preview production build | | npm run storybook | Start Storybook development server | | npm run build-storybook | Build static Storybook site | | npm run test | Run tests | | npm run test:watch | Run tests in watch mode | | npm run create-component | Create a new component |

🧩 Components

The library includes the following components:

Form Controls

• Button - Interactive button component with various styles
• Checkbox - Checkbox input with label support
• DropdownInput - Dropdown selection input
• InputText - Text input field with validation
• InputMoney - Currency input field
• InputCounter - Numeric counter input
• IbanInput - IBAN input with validation
• PhoneInput - Phone number input
• RadioButton - Radio button input with grouping
• TextareaInput - Multi-line text input
• ToggleSwitch - Toggle switch component
• ZipCodeInput - Zip Code input
• Chip - Compact elements that represent an input, attribute, or action
• Tag - Label for categorization

Navigation

• Breadcrumbs - Navigation breadcrumb component
• Pagination - Pagination component for content navigation
• SidePanel - Side navigation panel

Feedback

• ToasterAlert - Toast notification component
• Tooltip - Tooltip component for additional information
• Loading - Loading state indicators
• Modal - Dialogs and modal windows

Data Display

• Table - Data table with various features
• Accordion - Expandable content sections
• Card - Container for content
• Icon - Icon component

Design System

• Colors - Design system color tokens
• Typography - Typography styles and tokens
• Utils - Utility classes and mixins

📚 Usage

Basic Usage

<!-- Import the component -->
<script type="module" src="path/to/ctt-web-components.js"></script>

<!-- Use the component -->
<ctt-button variant="primary">Click me</ctt-button>

With TypeScript

import { CttButton } from 'ctt-web-components';

// Use in your application
const button = document.createElement('ctt-button');
button.variant = 'primary';
button.textContent = 'Click me';
document.body.appendChild(button);

Component Properties

Each component comes with comprehensive properties and events. Check the individual component documentation in Storybook for detailed usage examples.

• Storybook: https://storybook.js.org/
• Vitest: https://vitest.dev/
• Playwright: https://playwright.dev/
• JSDoc: https://jsdoc.app/

🎨 Design System

The components follow the CTT design system with:

• Color Tokens: Consistent color palette across all components
• Typography: Standardized font sizes, weights, and line heights
• Spacing: Consistent spacing values
• Layout: Grid and flexbox utilities

Design Tokens

/* Example design tokens */
:root {
  --ctt-color-primary: #007bff;
  --ctt-color-secondary: #6c757d;
  --ctt-spacing-xs: 0.25rem;
  --ctt-spacing-sm: 0.5rem;
  --ctt-font-size-base: 1rem;
}

🔧 Creating New Components

Use the built-in component generator to create new components:

npm run create-component MyNewComponent

This will generate:

• Component TypeScript implementation
• CSS file with design tokens
• Storybook stories
• Unit tests
• README documentation

🧪 Testing

Running Tests

# Run all tests - script already prepared
npm run test

# Run tests in watch mode
npm run test:watch

Linting & Formatting

The project uses ESLint for code quality and Prettier for code formatting.

# Check for linting errors
npm run lint

# Fix auto-fixable linting errors
npm run lint:fix

# Format code with Prettier
npm run format

Accessibility Testing

Accessibility is a core principle of the CTT Design System. We are committed to ensuring our components are usable by everyone, regardless of their abilities or the devices they use.

Tools & Standards: We utilize Playwright combined with axe-core to perform automated accessibility audits. Our tests are configured to strictly enforce WCAG 2.1 Level A and AA standards.

What we test: The npm run test:a11y command executes a suite that:

1. Scans Storybook Stories: Navigates to the default story of each component.
2. Validates Compliance: Checks against rulesets for:
   • ❌ Color Contrast ratios
   • ⌨️ Keyboard navigation and focus management
   • 🏷️ ARIA attributes and labels
   • 🏗️ Semantic HTML structure
3. Reports Violations: Fails the build if any violations are detected, ensuring no accessibility regressions are merged.

Why verify?

• Legal Compliance: Meets EU and national accessibility directives.
• Inclusivity: Ensures a seamless experience for users relying on screen readers and assistive technologies.
• Quality Code: Accessible code is often cleaner, more semantic, and better structured.

# Run accessibility tests
npm run test:a11y

Test Structure

Tests and Stories are located in src/storybook/stories/[ComponentName]/ directories, separate from the component implementation in src/components/:

• *.test.ts - Unit and interaction tests
• *.stories.ts - Storybook stories (also serve as integration tests)

Browser Testing

The project uses Playwright for browser testing to ensure components work correctly across different browsers.

📖 Documentation

Storybook

Access comprehensive component documentation at:

npm run storybook
# Opens at http://localhost:6006

Component READMEs

Each component has its own README with:

• Usage examples
• API documentation
• Design considerations
• Accessibility notes

🚀 Build and Deployment

Production Build

npm run build

This creates optimized bundles in the dist/ directory.

Storybook Build

npm run build-storybook

Creates a static Storybook site in storybook-static/.

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/new-component
3. Make your changes
4. Add tests for your changes
5. Run tests: npm run test
6. Build and test Storybook: npm run build-storybook
7. Commit your changes: git commit -m 'Add new component'
8. Push to the branch: git push origin feature/new-component
9. Submit a pull request

Code Style

• Follow TypeScript best practices
• Use consistent naming conventions
• Add JSDoc comments for public APIs
• Ensure accessibility compliance
• Write comprehensive tests

📋 Browser Support

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)

📄 License

[Add your license information here]

🆘 Support

For questions and support:

• Create an issue
• Documentation
• Contact the team

🗺️ Roadmap

• [ ] Additional form components
• [ ] Data visualization components
• [ ] Advanced layout components
• [ ] Theme customization system
• [ ] Performance optimizations

Built with ❤️ by the CTT team using Lit and Storybook.