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

``bash
npm install ctt-web-components
`

🛠️ Development

$3

- Node.js (v18 or higher)
- npm

$3

1. Clone the repository

`bash
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.

`bash
# Install core dependencies
npm install

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

3. Start development server

`bash
npm run dev
`

4. Start Storybook
`bash
npm run storybook
`

$3

| 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:

$3

- 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

$3

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

$3

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

$3

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

$3

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

📚 Usage

$3

`html




Click me
`

$3

`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);
`

$3

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

$3

`css
/ 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:

`bash
npm run create-component MyNewComponent
`

This will generate:

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

🧪 Testing

$3

`bash


Run all tests - script already prepared

npm run test

Run tests in watch mode

npm run test:watch
`

$3

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

`bash


Check for linting errors

npm run lint

Fix auto-fixable linting errors

npm run lint:fix

Format code with Prettier

npm run format
`

$3

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.

`bash


Run accessibility tests


npm run test:a11y
`

$3

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)

$3

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

📖 Documentation

$3

Access comprehensive component documentation at:

`bash
npm run storybook


Opens at http://localhost:6006


`

$3

Each component has its own README with:

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

🚀 Build and Deployment

$3

`bash
npm run build
`

This creates optimized bundles in the dist/ directory.

$3

`bash
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

$3

- 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.