DEV Community: Sergio Azócar

oxlint-tailwindcss: the linting plugin Tailwind v4 needed

Sergio Azócar — Mon, 23 Mar 2026 21:38:08 +0000

From problem to open-source: the perfect opportunity to contribute

The day the oxc team opened the alpha for native oxlint plugins, it was the perfect excuse to solve a problem I'd been having at my current job for a while — linting Tailwind CSS classes with oxlint.

If you use Tailwind CSS v4 with oxlint, the existing linting options aren't built for that combo. eslint-plugin-tailwindcss is solid but lives in the ESLint world and its v4 support is still partial. eslint-plugin-better-tailwindcss works in oxlint through the jsPlugins compatibility layer, and it gets the job done — but it's not a native plugin and its rules are more limited. Neither was designed specifically for oxlint + Tailwind CSS v4.

So I built it.

What is oxlint-tailwindcss

A native oxlint plugin with 22 linting rules designed exclusively for Tailwind CSS v4. It's not an ESLint port or a wrapper — it uses the @oxlint/plugins API directly.

This matters because being native means it shares the same parsing cycle as oxlint. There's no interoperability overhead, no translation layer. It's as fast as oxlint itself, and it shows.

Zero configuration

The plugin auto-detects your Tailwind CSS entry point. If your file is called app.css, globals.css, main.css, tailwind.css (or any of the conventional names) and contains @import "tailwindcss", it finds it automatically. No configuration needed.

{
  "jsPlugins": ["oxlint-tailwindcss"],
  "rules": {
    "tailwindcss/no-unknown-classes": "error",
    "tailwindcss/no-conflicting-classes": "error",
    "tailwindcss/enforce-sort-order": "warn"
  }
}

The design system is loaded once and shared across all rules. Efficient.

If you have a non-conventional entry point you can still configure it.

22 rules in four categories

Correctness — Catch real bugs

Correctness rules catch bugs before they reach the browser.

no-unknown-classes detects classes that don't exist in your design system and suggests fixes for typos:

<div className="flex itms-center bg-blu-500" />
//                   ^^^^^^^^^^^
// "itms-center" is not a valid Tailwind CSS class.
// Did you mean "items-center"?

no-conflicting-classes tells you exactly which CSS property is conflicting and which class wins:

<div className="text-red-500 text-blue-500" />
// "text-red-500" and "text-blue-500" affect "color".
// "text-blue-500" takes precedence (appears later).

no-dark-without-light detects when you use dark: without a base class, something that often causes missing styles in light mode:

// ❌ — what background does it have in light mode?
<div className="dark:bg-gray-900" />

// ✅
<div className="bg-white dark:bg-gray-900" />

no-contradicting-variants catches redundant variants where the base class already applies unconditionally:

// ❌ — dark:flex is redundant, flex already applies always
<div className="flex dark:flex" />

Also included: no-duplicate-classes (with autofix), no-deprecated-classes (with autofix and v4 mapping), and no-unnecessary-whitespace.

Style — Team consistency

enforce-sort-order sorts classes according to the official Tailwind CSS order (with autofix). It has a strict mode that also groups by variant.

enforce-shorthand converts mt-2 mr-2 mb-2 ml-2 to m-2, w-full h-full to size-full, and many more combinations. All with autofix.

enforce-logical converts physical properties to logical ones for LTR/RTL support: ml-4 → ms-4, left-0 → start-0. Its inverse, enforce-physical, does the opposite for projects that are LTR-only and prefer consistency with physical properties. Both with autofix.

enforce-consistent-variable-syntax normalizes CSS variable syntax between bg-[var(--primary)] and v4's shorthand bg-(--primary).

And four more rules: enforce-canonical, enforce-consistent-important-position (default suffix, v4's canonical form), enforce-negative-arbitrary-values, and consistent-variant-order.

Complexity — Keep code manageable

max-class-count warns when an element exceeds 20 classes (configurable). It's the signal that it's time to extract a component.

enforce-consistent-line-wrapping controls the class string length by print width or by number of classes per line.

Restrictions — Design system rules

no-hardcoded-colors forbids hardcoded colors like bg-[#ff5733] in arbitrary brackets — the typical shortcut that erodes your design system.

no-arbitrary-value and no-unnecessary-arbitrary-value (with autofix) control the use of arbitrary values. The latter detects when you use h-[auto] but h-auto exists.

no-restricted-classes allows blocking specific classes by name or regex, with custom messages.

Class extraction

The parser is what makes all of this work reliably. It's not a regex that looks for className= and hopes for the best. It extracts classes from:

JSX attributes (className, class)
Template literals with interpolation
Ternaries
Utility functions: cn(), clsx(), cx(), cva(), twMerge(), twJoin(), and more
Full cva() — base, variants, compoundVariants
Full tv() — base, slots, variants with slot objects, compoundSlots
Tagged templates (tw\...``)
Variables by name (className, classes, style, styles)

It handles nested brackets, nested calc, arbitrary variants, quoted values, important modifier, negative values, and named groups/peers. The edge cases that break other parsers.

The story behind it

I started by planning what I wanted, the stack I was going to use, and how I wanted everything to work. After planning the implementation with Claude Code, the iteration began until reaching the current 22 rules. The repo includes a CLAUDE.md and configured skills that allow any contributor to use the same workflow to write new rules — the same tool the plugin was built with. If you want to add a rule, Claude Code already knows how to do it in this project.

The project runs entirely on the VoidZero tool ecosystem. tsdown for the build, oxfmt for formatting, vitest for testing, tsgo (native TypeScript 7 in Go) for type checking, and of course oxlint for linting the plugin itself. Every tool in the chain is built on Rust or optimized for speed.

It wasn't a cosmetic decision — it was deliberate dogfooding. If you're going to make a plugin for oxlint, it makes sense that the entire toolchain is from the same ecosystem. And if you're going to develop with an AI agent, it makes sense that the repo is prepared for it.

Getting started

`bash pnpm add -D oxlint-tailwindcss `

Add the plugin to your .oxlintrc.json:

`json { "jsPlugins": ["oxlint-tailwindcss"], "rules": { "tailwindcss/no-unknown-classes": "error", "tailwindcss/no-duplicate-classes": "error", "tailwindcss/no-conflicting-classes": "error", "tailwindcss/no-deprecated-classes": "error", "tailwindcss/no-unnecessary-whitespace": "error", "tailwindcss/enforce-sort-order": "warn", "tailwindcss/enforce-shorthand": "warn", "tailwindcss/no-hardcoded-colors": "warn" //... } } `

Run oxlint. That's it.

Try it

The plugin is at v0.1.x — functional, tested, and ready for production use (some companies are already using it). But a linter gets better with real feedback from real projects.
If you try it and find a case it doesn't handle well, open an issue. If you want to contribute a rule, the repo is already set up so you can iterate with Claude Code from minute one. And if it was simply useful to you, a star on GitHub helps more people find it.

GitHub · npm

oxlint-tailwindcss: el plugin de linting que Tailwind v4 necesitaba

Sergio Azócar — Mon, 23 Mar 2026 21:38:01 +0000

Del problema al open-source: la oportunidad perfecta para contribuir

El día que el equipo de oxc abrió el alpha de plugins nativos para oxlint, fue la excusa perfecta para solucionar un problema que llevaba tiempo teniendo en mi trabajo actual, lintear las clases de Tailwind CSS con oxlint.

Si usas Tailwind CSS v4 con oxlint, las opciones de linting existentes no están pensadas para ese combo. eslint-plugin-tailwindcss es sólido pero vive en el mundo de ESLint y su soporte de v4 todavía es parcial. eslint-plugin-better-tailwindcss funciona en oxlint a través de la capa de compatibilidad jsPlugins, y hace el trabajo — pero no es un plugin nativo y sus reglas son más acotadas. Ninguno fue diseñado específicamente para oxlint + Tailwind CSS v4.

Así que lo construí.

Qué es oxlint-tailwindcss

Un plugin nativo de oxlint con 22 reglas de linting diseñadas exclusivamente para Tailwind CSS v4. No es un port de ESLint ni un wrapper — usa directamente la API de @oxlint/plugins.

Esto importa porque al ser nativo, comparte el mismo ciclo de parseo que oxlint. No hay overhead de interoperabilidad, no hay capa de traducción. Es tan rápido como oxlint mismo y se nota.

Cero configuración

El plugin auto-detecta tu entry point de Tailwind CSS. Si tu archivo se llama app.css, globals.css, main.css, tailwind.css (o cualquiera de los nombres convencionales) y contiene @import "tailwindcss", lo encuentra solo. No necesitas configurar nada.

{
  "jsPlugins": ["oxlint-tailwindcss"],
  "rules": {
    "tailwindcss/no-unknown-classes": "error",
    "tailwindcss/no-conflicting-classes": "error",
    "tailwindcss/enforce-sort-order": "warn"
  }
}

El design system se carga una vez y se comparte entre todas las reglas. Eficiente.

Si tienes un entry point distinto a lo convencional igual puedes configurarlo.

22 reglas en cuatro categorías

Correctness — Evitar errores reales

Las reglas de correctness atrapan bugs antes de que lleguen al navegador.

no-unknown-classes detecta clases que no existen en tu design system y sugiere correcciones para typos:

<div className="flex itms-center bg-blu-500" />
//                   ^^^^^^^^^^^
// "itms-center" is not a valid Tailwind CSS class.
// Did you mean "items-center"?

no-conflicting-classes te dice exactamente qué propiedad CSS está en conflicto y cuál clase gana:

<div className="text-red-500 text-blue-500" />
// "text-red-500" and "text-blue-500" affect "color".
// "text-blue-500" takes precedence (appears later).

no-dark-without-light detecta cuando usas dark: sin una clase base, algo que suele causar estilos faltantes en light mode:

// ❌ — ¿qué fondo tiene en light mode?
<div className="dark:bg-gray-900" />

// ✅
<div className="bg-white dark:bg-gray-900" />

no-contradicting-variants atrapa variantes redundantes donde la clase base ya aplica incondicionalmente:

// ❌ — dark:flex es redundante, flex ya aplica siempre
<div className="flex dark:flex" />

También están no-duplicate-classes (con autofix), no-deprecated-classes (con autofix y mapping de v4), y no-unnecessary-whitespace.

Style — Consistencia del equipo

enforce-sort-order ordena las clases según el orden oficial de Tailwind CSS (con autofix). Tiene un modo strict que además agrupa por variante.

enforce-shorthand convierte mt-2 mr-2 mb-2 ml-2 en m-2, w-full h-full en size-full, y muchas más combinaciones. Todo con autofix.

enforce-logical convierte propiedades físicas en lógicas para soporte LTR/RTL: ml-4 → ms-4, left-0 → start-0. Su inversa, enforce-physical, hace lo contrario para proyectos que son solo LTR y prefieren consistencia con propiedades físicas. Ambas con autofix.

enforce-consistent-variable-syntax normaliza la sintaxis de variables CSS entre bg-[var(--primary)] y la shorthand de v4 bg-(--primary).

Y otras cuatro reglas más: enforce-canonical, enforce-consistent-important-position (default suffix, la forma canónica de v4), enforce-negative-arbitrary-values y consistent-variant-order.

Complexity — Mantener el código manejable

max-class-count avisa cuando un elemento supera las 20 clases (configurable). Es la señal de que es hora de extraer un componente.

enforce-consistent-line-wrapping controla el largo del string de clases por print width o por cantidad de clases por línea.

Restrictions — Reglas del design system

no-hardcoded-colors prohíbe colores hardcodeados como bg-[#ff5733] en brackets arbitrarios — el típico atajo que erosiona tu design system.

no-arbitrary-value y no-unnecessary-arbitrary-value (con autofix) controlan el uso de valores arbitrarios. La segunda detecta cuando usas h-[auto] pero existe h-auto.

no-restricted-classes permite bloquear clases específicas por nombre o regex, con mensajes custom.

Extracción de clases

El parser es lo que hace que todo esto funcione de manera confiable. No es un regex que busca className= y reza. Extrae clases de:

Atributos JSX (className, class)
Template literals con interpolación
Ternarios
Funciones de utilidad: cn(), clsx(), cx(), cva(), twMerge(), twJoin(), y más
cva() completo — base, variants, compoundVariants
tv() completo — base, slots, variants con objetos de slots, compoundSlots
Tagged templates (tw\...``)
Variables por nombre (className, classes, style, styles)

Maneja nested brackets, calc anidado, arbitrary variants, quoted values, important modifier, negative values y named groups/peers. Los edge cases que rompen otros parsers.

La historia detrás

Partí planificando qué quería, el stack que iba a usar y cómo quería que funcionara todo. Después de planificar la implementación con Claude Code, arrancó la iteración hasta conseguir las 22 reglas actuales. El repo incluye un CLAUDE.md y skills configuradas que permiten a cualquier contribuidor usar el mismo workflow para escribir reglas nuevas — la misma herramienta con la que se construyó el plugin. Si quieres agregar una regla, Claude Code ya sabe cómo hacerlo en este proyecto.

El proyecto corre completamente sobre el ecosistema de herramientas de VoidZero. tsdown para el build, oxfmt para el formateo, vitest para testing, tsgo (TypeScript 7 nativo en Go) para el type checking, y por supuesto oxlint para el linting del propio plugin. Cada herramienta en la cadena está construida sobre Rust u optimizada para velocidad.

No fue una decisión cosmética — fue dogfooding deliberado. Si vas a hacer un plugin para oxlint, tiene sentido que todo el toolchain sea del mismo ecosistema. Y si vas a desarrollar con un agente de IA, tiene sentido que el repo esté preparado para ello.

Cómo empezar

`bash pnpm add -D oxlint-tailwindcss `

Agrega el plugin a tu .oxlintrc.json:

Ejecuta oxlint. Eso es todo.

Pruébalo

El plugin está en v0.1.x — funcional, testeado y listo para usar en producción (algunas empresas ya lo están usando). Pero un linter se hace mejor con feedback real de proyectos reales.
Si lo pruebas y encuentras un caso que no maneja bien, abre un issue. Si quieres contribuir una regla, el repo ya está preparado para que iteres con Claude Code desde el primer minuto. Y si simplemente te resultó útil, una estrella en GitHub ayuda a que más gente lo encuentre.

GitHub · npm

What I Learned Building Design Systems and What I Would Do Differently

Sergio Azócar — Thu, 26 Jun 2025 01:04:03 +0000

What is a Design System?

Simply put, it's a collection of rules, components, and guidelines that act as a single source of truth for designing and building interfaces.

A good Design System defines everything from colors, typography, and spacing, to how buttons, forms, alerts, and more should behave. But it goes far beyond the visual: it also defines how design and development communicate, how patterns are documented, and how the product evolves consistently.

The goal is for the entire team to speak the same language, design faster, and build products that feel coherent—without reinventing the wheel on every screen.

It’s not just a component library. It’s a way of working that seeks to align design, code, and user experience.

I'll go into more detail about how I built mine and what I learned, but first I want to tell you what it was like to face this idea from scratch.

How I Ended Up Building Design Systems

After working on different projects and teams, I began to notice patterns that kept repeating:

The same button designed three different ways
Inconsistent behavior in similar components
Duplicated or hard-to-maintain code
Misunderstandings between design and development
Interfaces that looked great in Figma, but not in production

Every time a product grew, so did the visual and technical chaos. And with it, the time we lost solving the same problems over and over again.

That’s when I realized we needed more than just a component library. We needed a shared way to build interfaces, with clear rules, centralized decisions, and a source of truth for all teams.

Expectations vs. Reality

Remember when you had to do group projects at school?
Everyone did their part separately, put it all together at the end… and the result was a total "Frankenstein."

Well, building a Design System often feels like that 😅.

At first, you think it’s going to organize everything, magically uniting design and development. But in practice, misunderstandings, shortcuts, and crossed decisions appear, and what should be a coherent system starts to fall apart.

Here are some of the biggest differences I experienced between what I imagined… and what actually happened:

🧠 Expectation:

“I'll create a reusable component library and the team will happily use it.”

🧱 Reality:
Some devs ignore it, others break it, and others don’t know how to use it.
Without documentation, onboarding, and internal support, no one adopts it as you expected.

🎨 Expectation:

“The design is in Figma, I just have to replicate it.”

⚠️ Reality:
The design doesn’t consider states, errors, focus, interaction, loading...
I ended up making a lot of technical decisions that weren’t defined.

🧪 Expectation:

“Once the components are done, we won’t need to touch them again.”

🔄 Reality:
Design evolves, new requirements come up, and each change affects multiple parts of the system.
A Design System needs constant maintenance.

🧩 Expectation:

“I’ll create generic and reusable components for everything.”

🧨 Reality:
Overly flexible components end up being hard to maintain, test, or understand.
Sometimes it’s better to have clear variants than a single component with 15 props.

👥 Expectation:

“Design and development will work as one team.”

📉 Reality:
Without clear processes and a common language, misunderstandings happen all the time.
Collaboration isn’t automatic—you have to build those bridges intentionally.

📦 Expectation:

“With Tailwind, I can do everything without a Design System.”

🔍 Reality:
Tailwind helps, but without shared design decisions, tokens, and a clear structure, your project still becomes inconsistent.

⏳ Expectation:

“I'll have the system ready in a few weeks.”

📆 Reality:
A Design System is never finished. It’s a living system that grows, adapts, and needs to evolve alongside your product.

To understand it better, let’s break down the needs of each team:

Design and Development Needs

When you set out to build a Design System—whether from scratch or based on an existing foundation—there are always two sides of the same coin: what Design and Development want and need. That’s where all the ~~problems~~ challenges begin.

Let’s take a look at what each team needs.

Design 🎨

Visual consistency: A unified visual language (colors, typography, spacing, iconography, etc.).
Speed and efficiency: The ability to design interfaces without reinventing the same components every time.
Scalable designs: What works on one screen should work on others (web, mobile, responsive...).
Clear, reusable design tokens: Technical definitions for colors, sizes, fonts, z-index, etc.
Direct alignment with implementation: What’s designed should look the same in production.

Development 💻

True component reuse: A stable, well-documented, and easy-to-use library.
Functional and technical consistency: Same prop patterns, slots, states, accessibility, validation, etc.
Ease of maintenance: Clean code, clear naming, tests, and no duplicated logic.
Living documentation: Storybook (or similar), with real examples—not just theory.
Adaptability across contexts: A button (for example) should work the same in all our applications.

Each team has its own priorities, but for a Design System to work, they must collaborate, making decisions based on shared definitions. That’s where the real intersection happens.

Shared Needs: The Balance Point 🤝

Common language: Tokens, component names, variants, states. Everyone should speak the same language.
Smooth design–development process: Clear handoffs from Figma (or whatever tool is used), efficient handovers, mutual feedback.
Versioning and change control: So that design changes can be implemented and communicated without breaking the system.
Cross-team adoption: It shouldn’t be stuck in one team. It has to be easy to understand and use by everyone.

In short, a Design System needs to be strict enough to uphold design definitions and prevent undocumented visual changes, but flexible enough to extend and adapt without breaking things.

How to Drive System Adoption

Having a technically perfect Design System doesn’t mean much if no one uses it.

One of the biggest challenges isn’t building the system—it’s getting the team to actually adopt it. And I don’t just mean “being aware it exists,” I mean integrating it into their daily workflow, respecting it, questioning it, and keeping it alive.

Here’s what helped me (and what I learned the hard way):

Involve people from the start: If the system is built in isolation, it will generate resistance. The more voices involved early on, the more ownership it creates.
Show value quickly: A useful, well-documented, easy-to-use component is worth more than a promise of “someday we’ll have everything tidy.”
Document with empathy: It’s not just about how to use a component, it’s about how someone new will understand it. Real examples, screenshots, use cases, FAQs—all of it helps.
Provide internal support: If someone has a problem with a component, there should be a quick way to solve it. Slack, issues, pair programming… whatever it takes, just don’t let people feel alone—and have a clear way to report issues.
Celebrate usage: When someone adopts a component, improves it, or reports a bug—celebrate it. Small recognitions help the system feel alive, collaborative, and valuable.

Adoption isn’t an event—it’s a process. It takes time, patience, and lots of communication.

Lessons Learned and Final Recommendations

After all this, here are some takeaways I wish I had known earlier:

A Design System isn’t a project—it’s a product. And like any product, it needs research, design, maintenance, communication, and evolution.
Start with what hurts the most: Don’t try to solve everything from day one. Identify your biggest pain points and start there.
Perfection isn’t the goal: There will always be debt, components to improve, and decisions to revisit. The goal is usefulness and evolution.
No adoption, no system: If the team doesn’t use it, it’s just another folder in your repo.
Every team is different: Don’t copy someone else’s system expecting it to work the same. Get inspired, sure—but adapt it to your context.
Anticipate problems: Your Design System will break. Definitions will change. Plan for that. Build things modular and flexible.
Use Atomic Design: But use it wisely. Every component is a world of its own. The more atomic each one is, the easier it is to update or extend without breaking everything.

A Design System is a long-term investment. It can be challenging, even frustrating at times, but once it starts working, the whole team benefits from speed, consistency, and confidence.

Lo que aprendí construyendo Design Systems y que haría diferente

Sergio Azócar — Thu, 26 Jun 2025 01:02:54 +0000

¿Qué es un Design System?

En simple, es una colección de reglas, componentes y directrices que actúan como una única fuente de la verdad para diseñar y construir interfaces.

Un buen Design System define desde los colores, tipografías y espaciados, hasta cómo deben comportarse los botones, formularios, alertas, y más. Pero va mucho más allá de lo visual: también establece cómo se comunican diseño y desarrollo, cómo se documentan los patrones y cómo evoluciona el producto de forma consistente.

La idea es que todo el equipo hable el mismo idioma, diseñe más rápido y construya productos que se sientan coherentes, sin reinventar la rueda en cada pantalla.

No es solo una librería de componentes. Es una forma de trabajar que busca alinear diseño, código y experiencia de usuario.

Más adelante voy a entrar en detalle sobre cómo lo construí y qué aprendí, pero primero quiero contarte cómo fue enfrentarme a esta idea desde cero.

Cómo terminé construyendo Design Systems

Después de trabajar en distintos proyectos y equipos, empecé a notar patrones que se repiten constantemente:

El mismo botón diseñado de tres formas distintas
Comportamientos inconsistentes en componentes similares
Código duplicado o difícil de mantener
Malentendidos entre diseño y desarrollo
Interfaces que se veían bien en Figma, pero no en producción

Cada vez que un producto crecía, también lo hacía el caos visual y técnico. Y con él, el tiempo que perdíamos resolviendo los mismos problemas una y otra vez.

Ahí fue cuando entendí que necesitábamos algo más que una librería de componentes. Necesitábamos una forma compartida de construir interfaces, con reglas claras, decisiones centralizadas y una fuente de la verdad para todos los equipos.

Expectativa versus realidad

¿Te acuerdas cuando en el colegio te tocaba hacer un trabajo en grupo?

Cada uno hacía su parte por separado, lo juntaban todo al final… y el resultado era un verdadero "Frankenstein".

Bueno, construir un Design System se siente muchas veces así 😅.

Al principio crees que va a ordenar todo, que unirá diseño y desarrollo como por arte de magia. Pero en la práctica, aparecen los malentendidos, los atajos, las decisiones cruzadas, y lo que debería ser un sistema coherente empieza a desarmarse.

Estas fueron algunas de las diferencias más marcadas que viví entre lo que imaginaba… y lo que realmente pasó:

🧠 Expectativa:

“Voy a crear una librería de componentes reutilizables y el equipo la va a usar feliz.”

🧱 Realidad:

Algunos devs la ignoran, otros la rompen, otros no saben cómo usarla.

Sin documentación, onboarding y soporte interno, nadie la adopta como esperás.

🎨 Expectativa:

“El diseño está en Figma, así que solo tengo que replicarlo.”

⚠️ Realidad:

El diseño no contempla estados, errores, focus, interacción, loading...

Terminé tomando muchas decisiones técnicas que no estaban definidas.

🧪 Expectativa:

“Una vez que los componentes están hechos, no hay que tocarlos más.”

🔄 Realidad:

El diseño evoluciona, aparecen nuevos requerimientos, y cada cambio afecta múltiples partes del sistema.

Un Design System necesita mantenimiento constante.

🧩 Expectativa:

“Voy a crear componentes genéricos y reutilizables para todo.”

🧨 Realidad:

Componentes ultra flexibles terminan siendo difíciles de mantener, testear o entender.

A veces es mejor tener variantes claras que un solo componente con 15 props.

👥 Expectativa:

“Diseño y desarrollo van a trabajar como un solo equipo.”

📉 Realidad:

Sin procesos claros y un lenguaje común, aparecen malentendidos todo el tiempo.

Colaborar no es automático: hay que construir puentes intencionalmente.

📦 Expectativa:

“Con Tailwind puedo hacer todo sin un Design System.”

🔍 Realidad:

Tailwind ayuda, pero sin decisiones de diseño compartidas, tokens y una estructura clara, tu proyecto igual se vuelve inconsistente.

⏳ Expectativa:

“En unas semanas tengo el sistema listo.”

📆 Realidad:

Un Design System no se termina. Es un sistema vivo que crece, se adapta y necesita evolucionar junto a tu producto.

Para entenderlo mejor, analicemos las necesidades de cada uno:

Necesidades de Diseño y Desarrollo

Cuando te enfrentas a crear un Design System —ya sea desde cero o a partir de una base existente— siempre aparecen dos caras de la misma moneda: lo que quiere y necesita tanto Diseño cómo Desarrollo. Es ahí donde empiezan todos los ~~problemas~~ desafíos.

Para contextualizar un poco analicemos las necesidades de cada equipo.

Diseño 🎨

Consistencia visual: Un lenguaje visual unificado (colores, tipografías, espaciados, iconografía, etc.).
Velocidad y eficiencia: Poder diseñar interfaces sin reinventar los mismos componentes cada vez.
Escalabilidad de diseños: Que lo que funciona en una pantalla también funcione en otras (web, mobile, responsive...).
Tokens de diseño claros y reutilizables: Definición técnica de colores, tamaños, fuentes, z-index, etc.
Relación directa con la implementación: Que lo que diseñan se vea igual en producción.

Desarrollo 💻

Reutilización real de componentes: Librería estable, bien documentada y fácil de usar.
Consistencia funcional y técnica: Mismos patrones de props, slots, estados, accesibilidad, validación, etc.
Facilidad de mantenimiento: Código limpio, con nombres claros, tests, y sin lógica duplicada.
Documentación viva: Storybook o similar, con ejemplos reales, no solo teoría.
Adaptabilidad a contextos distintos: Que un botón (por ejemplo) funcione igual en cualquiera de las aplicaciones que tenemos.

Cada equipo tiene sus propias necesidades y prioridades, pero para que un Design System funcione, deben trabajar en conjunto, tomando decisiones basadas en definiciones compartidas. Ahí es donde deben aprovechar al máximo los puntos de unión entre ambos mundos.

Necesidades mutuas, el punto de equilibrio 🤝

Lenguaje común: Tokens, nombres de componentes, variantes, estados. Todos deben hablar el mismo idioma.
Proceso de diseño–desarrollo fluido: Entregas claras desde Figma (o lo que usen), handoffs eficientes, feedback mutuo.
Versionado y control de cambios: Para que los cambios en diseño se puedan implementar y comunicar sin romper el resto del sistema.
Adopción transversal del sistema: Que no se quede en un equipo. Tiene que ser fácil de usar y entender por todos.

En resumen, un Design System necesita ser lo suficientemente cerrado como para respetar las definiciones de diseño sin permitir cambios visuales arbitrarios, pero también lo suficientemente flexible como para extenderse y adaptarse sin romper nada.

Cómo lograr la adopción del sistema

Tener un Design System técnicamente impecable no sirve de mucho si nadie lo usa.

Uno de los mayores desafíos no es construir el sistema, sino lograr que el equipo lo adopte de verdad. Y no me refiero solo a “que lo conozcan”, sino a que lo integren en su día a día, lo respeten, lo cuestionen y lo mantengan vivo.

Algunas cosas que me funcionaron (y otras que aprendí a la fuerza):

Involucrar desde el inicio: Si el sistema se construye entre unos pocos, alejado del equipo, va a generar rechazo. Mientras más voces participen desde el comienzo, más pertenencia genera.
Mostrar valor rápidamente: Un componente útil, bien documentado y fácil de usar vale más que una promesa de “algún día vamos a tener todo ordenado”.
Documentar con empatía: No es solo escribir cómo usar un componente, es pensar en cómo lo entenderá alguien que llega por primera vez. Ejemplos reales, capturas, casos de uso, FAQs... todo suma.
Dar soporte interno: Si alguien tiene un problema con un componente, tiene que haber una forma rápida de resolverlo. Slack, issues, pair programming... lo que sea, pero que no sientan que están solos y sobre todo, un flujo claro de como reportar los errores.
Celebrar el uso: Cuando alguien adopta un componente, lo mejora o reporta un bug, hay que celebrarlo. Pequeños reconocimientos hacen que el sistema se vea como algo vivo, colaborativo y útil.

La adopción no es un evento, es un proceso. Y requiere tiempo, paciencia y mucha comunicación.

Lecciones aprendidas y recomendaciones

Después de todo este proceso, me quedo con varias ideas que ojalá hubiese sabido antes:

Un Design System no es un proyecto, es un producto. Y como todo producto, necesita investigación, diseño, mantenimiento, comunicación y evolución.
Empieza por lo que más duele: No intentes resolver todo desde el día uno. Identifica qué está causando más fricción hoy y empieza por ahí.
La perfección no es el objetivo: Siempre va a haber deuda, componentes por mejorar y decisiones que se pueden cuestionar. La clave es que sea útil y evolucione.
Sin adopción, no hay sistema: Si no lo usa el equipo, es solo una carpeta más en tu repo.
Cada equipo es distinto: No copies un sistema de otro lado esperando que funcione igual. Inspírate, sí, pero adapta todo a tu contexto y necesidades reales.
Anticipa los problemas: Tu Design System puede y va a fallar, habrán cambios de definiciones y de diseño. Ten eso en cuenta para que construyas todo de forma modular y flexible.
Utiliza Atomic Design: Pero utilizalo bien, cada componente es un mundo por si mismo, mientras más atómico sea cada uno, más fácil es modificarlo o extenderlo sin romperlo todo.

Un Design System es una inversión a largo plazo. Puede ser desafiante, incluso frustrante a veces, pero cuando empieza a funcionar, todo el equipo gana en velocidad, consistencia y confianza.

Screaming Architecture: The Key to a Scalable Frontend

Sergio Azócar — Thu, 19 Jun 2025 03:17:57 +0000

What is Screaming Architecture?

When you open a project, do you instantly know what it's about, or do you have to dig into the code to understand it? If your answer is the latter, this article is for you.

I'm going to tell you about Screaming Architecture, a code organization approach that, instead of screaming the technology you use, screams the business's purpose and its functionalities.

Why use it in the frontend?

🧭 Immediate clarity: You understand the code's purpose just by looking at its structure.
🧱 True scalability: Each functionality grows in an isolated, orderly manner.
👥 Faster onboarding: New devs understand the project better and quicker.
🧹 Safer refactorings: Everything is more encapsulated.
🚀 Facilitates testing, modularization, and team division.

The Problem with "Generic" Structures

Most frontend projects, especially at the beginning, use a folder structure based on technical types: components/, views/, services/, utils/, store/, etc.

src/
├── components/
├── views/
├── services/
├── utils/
└── store/
└── ...

While it's a starting point, this structure has its problems, especially as your application grows:

Logic dispersion: For a single functionality (e.g., "User Management"), its parts (UI components, store logic, API calls) are scattered throughout the entire project.
Navigation difficulty: You have to jump between many folders to understand how a complete feature works.
Painful maintenance: A change in one function might require modifying files in several folders, increasing the risk of introducing errors.
Infrastructure coupling: The structure tells you how it's built (with services, components), not what your business does.

Imagine a house blueprint. You don't see a "bricks" section, another for "cement," and another for "windows." You see "kitchen," "bedroom," "bathroom." The blueprints "scream" the purpose and functions of each space.

Screaming Architecture seeks the same for your code. Your high-level folder structure should "scream" the main features or business domains of your application, not the technologies you use.

Advantages of using Screaming Architecture

Implementing this approach isn't just about aesthetics; it brings tangible benefits that allow you to scale your application and your team.

Instant understanding: You open the project and, at a glance, you know what the business does.
Fast onboarding: New developers understand the business structure much faster.
Simplified maintenance: Changes to a functionality are kept localized within its own module.
Isolated changes, fewer errors: You reduce the risk of breaking other parts of the system when modifying a feature.
More scalable code: You can add new functionalities (features) without affecting existing code.
Intuitive navigation: You look for business functionalities, not generic file types.
Less coupling: The core business logic is more independent of technical details.
Safer refactorings: Moving or refactoring an entire feature is less risky.
Facilitates testing: Functionalities are easier to isolate and test.
Your project becomes predictable: Growth is organized and controlled.

Applying Screaming Architecture

We'll use a Vue project as an example, but it's 100% applicable to any other technology.

The key is to group code by features or business domains. Each feature folder will contain everything needed for that functionality.

Here's a practical example of what the structure might look like in your project:

src/
├── modules/            # Could also be called "Features" or "Domain," something that groups
│   │                   # functionalities
│   ├── Auth/           # Everything related to authentication
│   │   ├── components/ # LoginButton.vue, RegisterForm.vue
│   │   ├── views/      # LoginView.vue, RegisterView.vue
│   │   ├── routes/     # Specific routes for this module
│   │   ├── store/      # auth.store.js (Pinia store for Auth)
│   │   └── services/   # auth.service.js (Auth API calls)
│   ├── Products/       # Everything related to products
│   │   ├── components/ # ProductCard.vue, ProductList.vue
│   │   ├── views/      # ProductsView.vue, ProductDetailView.vue
│   │   ├── routes/     # Specific routes for this module
│   │   ├── store/      # products.store.js
│   │   └── services/   # products.service.js
│   ├── Orders/         # Everything related to orders
│   │   ├── components/
│   │   ├── routes/
│   │   ├── views/
│   │   ├── store/
│   │   └── services/
│   └── Profile/        # And so on for other features...
│       ├── components/
│       └── ...
├── shared/             # Truly cross-cutting elements that don't belong to a
│   │                   # specific feature
│   ├── ui/
│   │   ├── components/ # BaseButton.vue, ModalBase.vue (generic UI components)
│   │   └── composables/# useModal.js, useDarkMode.js (composables that only affect
│   │                   # UI components)
│   ├── composables/    # useDebounce.js, useLocalStorage.js (reusable logic
│   │                   # without business state)
│   ├── utils/          # formatDate.js, validateEmail.js
│   └── assets/         # Global images, base styles
├── layouts/            # Layout templates (DefaultLayout.vue, AuthLayout.vue)
├── router/             # General application router
├── app.vue
├── main.js
└── vite.config.js      # Vite configuration

The structure mentioned is just an example; you can adapt it to your own needs.

The important thing is that each Module has its own folder structure as you need it; you won't always have a "Store" or "Services" in every module, for example.

When to Use Screaming Architecture? (and when not to?)

This approach is powerful, but it's not a silver bullet for all projects:

Ideal for:

Medium to large projects with complex business logic.
Applications expected to grow significantly.
Teams with multiple developers.
When clarity and long-term maintenance are priorities.

Perhaps excessive for:

Very small projects or MVPs ("Minimum Viable Products") that you know won't scale much.
Very simple CRUD (Create, Read, Update, Delete) applications where the logic is minimal.

Considerations:

If your project has the potential to grow, adopting Screaming Architecture from the beginning, or at least in early stages, will save you a lot of headaches in the future.
In an existing application, you can progressively adopt Screaming Architecture by migrating one module at a time.

Conclusion: Make Your Architecture Scream Its Purpose

Screaming Architecture is more than just a way to organize folders; it's a mindset that prioritizes business cohesion over technical infrastructure. By making your code scream its functionalities, you not only improve readability and maintainability but also lay a solid foundation for your frontend to scale efficiently and in a controlled manner.

Are you ready for your next project's architecture to start screaming?

Screaming Architecture: La Clave para un Frontend Escalable

Sergio Azócar — Thu, 19 Jun 2025 03:16:03 +0000

¿Qué es Screaming Architecture?

Cuando abres un proyecto, ¿sabes al instante de qué trata, o tienes que bucear en el código para entenderlo? Si tu respuesta es lo segundo, este artículo es para ti.

Te voy a contar sobre Screaming Architecture, un enfoque de organización de código que, en lugar de gritar la tecnología que usas, grita el propósito del negocio y sus funcionalidades.

¿Por qué usarlo en el frontend?

🧭 Claridad inmediata: entendés el propósito del código con solo ver la estructura.
🧱 Escalabilidad real: cada funcionalidad crece de forma aislada y ordenada.
👥 Onboarding más rápido: nuevos devs entienden mejor y más rápido el proyecto.
🧹 Refactorizaciones más seguras: todo está más encapsulado.
🚀 Facilita pruebas, modularización y división de equipo.

El Problema de la Estructura "Genérica"

La mayoría de los proyectos frontend, especialmente al inicio, usan una estructura de carpetas basada en tipos técnicos: components/, views/, services/, utils/, store/, etc.

src/
├── components/
├── views/
├── services/
├── utils/
└── store/
└── ...

Si bien es un punto de partida, esta estructura tiene sus problemas, especialmente a medida que tu aplicación crece:

Dispersión de la lógica: Para una sola funcionalidad (ej. "Gestión de Usuarios"), sus partes (componentes de UI, lógica del store, llamadas a la API) están esparcidas por todo el proyecto.
Dificultad de navegación: Tienes que saltar entre muchas carpetas para entender cómo funciona una característica completa.
Mantenimiento doloroso: Un cambio en una función puede requerir modificar archivos en varias carpetas, aumentando el riesgo de introducir errores.
Acoplamiento a la infraestructura: La estructura te dice cómo está hecho (con servicios, componentes), no qué hace tu negocio.

Imagina el plano de una casa. No ves una sección de "ladrillos", otra de "cemento" y otra de "ventanas". Ves "cocina", "dormitorio", "baño". Los planos "gritan" el propósito y las funciones de cada espacio.

La Screaming Architecture busca lo mismo para tu código. Tu estructura de carpetas de alto nivel debería "gritar" las características principales o los dominios de negocio de tu aplicación, no las tecnologías que usas.

Ventajas de usar Screaming Architecture

Implementar este enfoque no es solo por estética, trae beneficios tangibles que te permiten escalar tu aplicación y tu equipo.

Entendimiento instantáneo: Abres el proyecto y de un vistazo sabes que hace el negocio.
Onboarding veloz: Nuevos desarrolladores entienden la estructura del negocio mucho más rápido.
Mantenimiento simplificado: Los cambios en una funcionalidad se mantienen localizados en su propio módulo.
Cambios aislados, menos errores: Reduces el riesgo de romper otras partes del sistema al modificar una feature.
Código más escalable: Puedes añadir nuevas funcionalidades (features) sin afectar el código de las existentes.
Navegación intuitiva: Buscas funcionalidades de negocio, no tipos de archivos genéricos.
Menos acoplamiento: La lógica de negocio central es más independiente de los detalles técnicos.
Refactorización más segura: Mover o refactorizar una feature entera es menos arriesgado.
Facilita el testing: Las funcionalidades son más fáciles de aislar y testear.
Tu proyecto se vuelve predecible: El crecimiento es organizado y controlado.

Aplicando Screaming Architecture

Tomaremos como ejemplo un proyecto de Vue, pero es 100% aplicable a cualquier otra tecnología.

La clave es agrupar el código por features o dominios de negocio. Cada carpeta de feature contendrá todo lo necesario para esa funcionalidad.

Aquí tienes un ejemplo práctico de cómo podría verse la estructura en tú proyecto:

src/
├── modules/              # También podría llamarse "Features" o "Domain", algo que agrupe
│   │                       las funcionalidades
│   ├── Auth/             # Todo lo relacionado con autenticación
│   │   ├── components/   # LoginButton.vue, RegisterForm.vue
│   │   ├── views/        # LoginView.vue, RegisterView.vue
│   │   ├── routes/       # Rutas específicas de este módulo
│   │   ├── store/        # auth.store.js (store de Pinia para Auth)
│   │   └── services/     # auth.service.js (llamadas a la API de Auth)
│   ├── Products/         # Todo lo relacionado con productos
│   │   ├── components/   # ProductCard.vue, ProductList.vue
│   │   ├── views/        # ProductsView.vue, ProductDetailView.vue
│   │   ├── routes/       # Rutas específicas de este módulo
│   │   ├── store/        # products.store.js
│   │   └── services/     # products.service.js
│   ├── Orders/           # Todo lo relacionado con pedidos
│   │   ├── components/
│   │   ├── routes/
│   │   ├── views/
│   │   ├── store/
│   │   └── services/
│   └── Profile/          # Y así sucesivamente para otras features...
│       ├── components/
│       └── ...
├── shared/               # Elementos verdaderamente transversales que no pertenecen a una
│   │                       feature específica
│   ├── ui/
│   │   ├── components/   # BaseButton.vue, ModalBase.vue (componentes UI genéricos)
│   │   └── composables/  # useModal.js, useDarkMode,js (composables que afectan sólo a
│   │                       componentes de UI)
│   ├── composables/      # useDebounce.js, useLocalStorage.js (lógica reutilizable
│   │                       sin estado de negocio)
│   ├── utils/            # formatDate.js, validateEmail.js
│   └── assets/           # Imágenes globales, estilos base
├── layouts/              # Plantillas de layout (DefaultLayout.vue, AuthLayout.vue)
├── router/               # Router general de la aplicación
├── app.vue
├── main.js
└── vite.config.js        # Configuración de vite

La estructura mencionada es sólo un ejemplo, puedes adaptarla según tus propias necesidades.

Lo importante es que cada Module tenga su propia estructura de carpetas según lo necesites, no siempre vas a tener un "Store" o "Services" en cada módulo, por ejemplo.

¿Cuándo Usar Screaming Architecture? (¿y cuándo no?)

Este enfoque es poderoso, pero no es la bala de plata para todos los proyectos:

Ideal para:

Proyectos medianos a grandes con lógica de negocio compleja.
Aplicaciones que se espera que crezcan significativamente.
Equipos con varios desarrolladores.
Cuando la claridad y el mantenimiento a largo plazo son prioritarios.

Quizás excesivo para:

Proyectos muy pequeños o MVPs ("Minimum Viable Products") que sabes que no escalarán mucho.
Aplicaciones CRUD (Crear, Leer, Actualizar, Borrar) muy simples donde la lógica es mínima.

Consideraciones:

Si tu proyecto tiene potencial de crecer, adoptar la Screaming Architecture desde el principio o al menos en fases tempranas, te ahorrará muchos dolores de cabeza en el futuro.
En una aplicación existente, puedes ir adoptando Screaming Architecture de forma progesiva, migrando un módulo a la vez.

Conclusión: Haz que tu Arquitectura Grite su Propósito

La Screaming Architecture es más que una simple forma de organizar carpetas; es una mentalidad que prioriza la cohesión del negocio sobre la infraestructura técnica. Al hacer que tu código grite sus funcionalidades, no solo mejoras la legibilidad y la mantenibilidad, sino que defines una base sólida para que tu frontend escale de forma eficiente y controlada.

¿Estás listo para que la arquitectura de tu próximo proyecto comience a gritar?