desy-html

An NPM library for building user interfaces for Government of Aragón web applications. It uses Vite, Tailwind CSS and Nunjucks to render HTML+CSS+JS components. It's useful to create lightweight webapps or HTML mockups.

Overview

desy-html is the core design system library that provides:

• Vite - Fast build tool and development server with hot module replacement
• Tailwind CSS v4 - Utility-first CSS framework
• Nunjucks - Powerful templating engine for generating HTML
• Sharp - Image optimization for production builds
• Accessible Components - Pre-built UI components following ARIA patterns

If you need a more powerful library based on this, use its Angular port instead: desy-angular

Quick Links

• Documentation: https://desy.aragon.es/
• Repository: https://bitbucket.org/sdaragon/desy-html/
• Starter Project: https://bitbucket.org/sdaragon/desy-html-starter/

How do I start a project that uses desy-html components?

To start a new project that uses desy-html as dependency, don't use this repo, use the desy-html-starter repo instead:

1. Download the desy-html-starter project from https://bitbucket.org/sdaragon/desy-html-starter
2. Personalize the downloaded project for your needs
3. You'll be able to use any desy-html component in that project

Prerequisites

Before you begin, ensure you have the following installed:

• Node.js >=20.19.2 <23.0.0
• npm >=10.0.0

Getting Started

1. Clone the Repository

git clone https://bitbucket.org/sdaragon/desy-html.git
cd desy-html

2. Install Dependencies

npm install

3. Start Development Server

npm run dev

This starts the Vite development server with hot module replacement. Open your browser at the URL displayed in the terminal output.

4. Build for Production

npm run build

This compiles HTML, purges and minifies CSS, and optimizes JavaScript into the /dist folder.

5. Preview Production Build

npm run preview

Project Structure

desy-html/
├── public/
│   └── images/                # Library images
├── src/
│   ├── css/                   # Stylesheets
│   ├── js/                    # JavaScript files
│   └── templates/
│       ├── components/        # UI component macros
│       ├── includes/          # Reusable template partials
│       └── pages/             # Page templates
├── docs/                      # Documentation files
├── vite.config.js             # Vite configuration
├── package.json
└── README.md

Styling

Using Tailwind CSS

The project uses Tailwind CSS v4. All Tailwind utility classes are available in your templates:

<div class="flex items-center gap-4 p-6 bg-white rounded-lg shadow">
  <h1 class="text-2xl font-bold text-gray-900">Hello World</h1>
</div>

Theme Variables

desy-html provides CSS custom properties (variables) for consistent theming. These are included in the main stylesheet.

Images

Image Structure

Images are stored in public/images/ and can be referenced in templates using the /images/ path:

<img src="/images/my-image.png" alt="Description">

Image Optimization

During production builds, images are automatically optimized using Sharp:

• Supported formats: jpg, png, webp, avif
• File sizes are optimized for production

Development Tips

Hot Module Replacement

The development server supports HMR. Changes to CSS, JavaScript, and templates will automatically refresh in the browser.

Debugging

• Check the browser console for JavaScript errors
• Use the Vite terminal output for build errors
• Inspect generated HTML in browser developer tools

Scripts Reference

| Command | Description | |---------|-------------| | npm run dev | Start development server with HMR | | npm run build | Build for production | | npm run preview | Preview production build locally |

Accessibility

All desy-html components are built with accessibility in mind:

• Proper ARIA attributes and roles
• Keyboard navigation support
• Screen reader compatibility
• Focus management

Browser Support

The project targets modern browsers. For specific compatibility information, refer to the desy documentation.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

Contact the Team

desy-html is maintained by a team at SDA Servicios Digitales de Aragón (Spain). If you want to know more about desy-html, please email any of the commiters.

Author

SDA Servicios Digitales de Aragón

License

This project is licensed under the EUPL-1.2 license.

For more information and detailed component documentation, visit https://desy.aragon.es/