desy-html

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:

• Download the desy-html-starter project from https://bitbucket.org/sdaragon/desy-html-starter
• Personalize the downloaded project for your needs
• 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
│   │   ├── aria/              # ARIA component implementations
│   │   ├── desy-html.js      # Main component exports
│   │   ├── headroom.min.js   # Headroom.js library
│   │   └── index.js          # Entry point
│   ├── templates/
│   │   ├── components/        # UI component macros
│   │   ├── includes/          # Reusable template partials
│   │   └── pages/             # Page templates
│   ├── main.js                # Main entry point
│   └── EUPL-1.2.txt          # License file
├── docs/                      # Documentation files
├── branding/                  # Branding assets and configuration
├── vite.config.js             # Vite configuration
├── package.json
└── README.md

Branding Customization

desy-html can be customized for different government organizations.

To customize:

• Edit branding/branding.config.js with your organization's information
• Replace logos in /branding/logos/
• Run npm run build

See branding/BRANDING.md for complete documentation.

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

• Fork the repository
• Create a feature branch
• Make your changes
• 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/