npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@540deg/ds

v0.2.0

Published

Sistema de diseño de 540: componentes React, tokens y estilos para montar charlas y webs.

Readme

540 Design System

El sistema de diseño de 540 en código: tokens, componentes React y documentación en Storybook. Sirve para montar las presentaciones de las charlas y la web con las mismas piezas.

Arrancarlo en un Mac

Necesitas Node.js (versión 24 o superior) y Git. Si no los tienes, se instalan con Homebrew:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
brew install node git

Después, en la app Terminal:

cd ~/Projects/540-ds
npm install
npm run storybook

Se abre solo en el navegador en http://localhost:6006. Para pararlo, Ctrl + C en la Terminal.

Otros comandos útiles:

| Comando | Qué hace | |---|---| | npm run storybook | Arranca el catálogo en local | | npm run build-storybook | Genera la versión estática para compartir (carpeta storybook-static) | | npx vitest run --project=storybook | Pasa las pruebas de todas las historias (render y accesibilidad) | | npx tsc -p tsconfig.app.json --noEmit | Comprueba los tipos de TypeScript | | npm run build:lib | Construye la librería npm en dist/ (ver «Usarlo en un proyecto React») | | npm run mcp:inspect | Abre el MCP del sistema en MCP Inspector (ver mcp/README.md) | | npm run test:mcp | Pasa las pruebas del MCP |

Cómo está organizado

src/
  tokens/            los valores con nombre (CSS)
    primitives.css         primitivos: --540-*
    semantic-color.css     colores por uso, con modo claro y oscuro
    semantic-typography.css  los trece estilos de texto y la escala de proyección
    semantic-measure.css   espacio, rellenos, tamaños, retícula, radios
    breakpoints.ts         los dos saltos (600 y 1024), como constantes
    manifest.ts            nombres y descripciones para las páginas de Fundamentos
  foundations/       las páginas de Fundamentos de Storybook
  components/
    atoms/           Text, Button, Logo, Image, ThemeToggle, Bullets, MenuItem, SocialIcon, Count
    molecules/       SectionHeader, Section, Card, Menu, CaseItem, TeamMember, Footer, NavMobile, Field, Carousel, Dialog, Grid, Question, Lists, Screenshot, Metric, Stack
    organisms/       Deck, Slide, Cover, Closing, Statements, BlockTitle, Story, Quote, Punchline, Timeline, Flow, Tools, Marquee, CardList, Form, LogoCarousel, DeckFooter, Blobs, Steps, Cycle, Sheet, ProgressBar, Heartbeat, Spotlight, Schema, Bars, Share
  templates/         TalkTemplate: la charla completa, con todas las paradas posibles
  hooks/             useReveal: cuándo una pieza entra en pantalla (contadores y gráficas)
  styles/global.css  reset y estilos base
  assets/            logotipo de 540 y muestras para las historias
.storybook/          configuración de Storybook (tema con la marca, barra de herramientas, portada de cada página)

Cada componente vive en su carpeta con la misma estructura:

Button/
  Button.tsx          el componente
  Button.module.css   sus estilos (CSS Modules, solo tokens semánticos)
  types.ts            opciones, tipos y valores por defecto
  index.ts            lo que se exporta
  Button.stories.tsx  las historias y los controles de Storybook
  _docs/Button.md     la ficha, en español

Cómo cambiar un token

Los tokens están en src/tokens. Hay dos niveles:

  • Primitivos (primitives.css): el valor en bruto con nombre. Por ejemplo --540-accent-yellow: #fef401;.
  • Semánticos (semantic-*.css): el uso, apuntando a un primitivo. Por ejemplo --color-bg-accent: var(--540-accent-yellow);. Los componentes solo usan estos.

Para cambiar un valor (un gris, un tamaño), edita el primitivo en primitives.css. Todo lo que lo use cambia a la vez, y las páginas de Fundamentos enseñan el valor nuevo porque lo leen del CSS.

Para cambiar a qué apunta un uso (que los bordes fuertes usen otro gris), edita el semántico en semantic-color.css. Hay un bloque para el tema claro (:root) y otro para el oscuro ([data-theme='dark']).

Cómo añadir un color

  1. Añade el primitivo en src/tokens/primitives.css, en su grupo, con el prefijo --540-:
    --540-status-blue: #2a5db0;
  2. Si va a tener un uso propio, añade el semántico en src/tokens/semantic-color.css, en el bloque claro y en el oscuro:
    --color-text-info: var(--540-status-blue);
  3. Añádelo a src/tokens/manifest.ts para que salga en la página Fundamentos / Color: en colorPrimitives el primitivo y en semanticColors el semántico, con su descripción.
  4. Guarda y mira la página de Color en Storybook.

Lo mismo vale para un tamaño de espacio o de letra: primitivo, semántico y manifest.

Normas para montar una charla

Están en src/docs/normas-charlas.md y se leen en Storybook en Introducción / Normas para charlas. Son obligatorias para cualquier presentación hecha con el sistema, la monte una persona o un agente: estructura, fotos de bloque, texto, márgenes, dónde puede ir el amarillo, efectos y la lista final de comprobación. El CLAUDE.md del proyecto obliga a leerlas antes de montar una charla con Claude.

Cómo pedir un componente nuevo

Abre Claude Code en la carpeta del proyecto y pídeselo con estos datos:

  • Qué es y para qué sirve, en una frase.
  • Dónde está en Figma (el enlace a la página) o en qué charla se usa, si existe ya.
  • Variantes, tamaños y estados que necesita, o «decide tú» si no lo sabes.
  • En qué nivel va: átomo, molécula u organismo.

Ejemplo:

Crea el componente Badge. Es una etiqueta pequeña para marcar un estado («Nuevo», «Borrador»). Está en la página Badge del Figma. Variantes neutral y accent, un solo tamaño. Es un átomo.

El componente se creará con la misma estructura que los demás (componente, estilos, tipos, historias y ficha), con su página Docs en Storybook y pasando las pruebas de accesibilidad.

Cómo compartir el catálogo con el equipo

npm run build-storybook

Deja una carpeta storybook-static con el catálogo completo en archivos estáticos. Se puede:

  • Abrir en local: haz doble clic en storybook-static/index.html.
  • Mandar comprimida: comprime la carpeta y envíala; quien la reciba la descomprime y abre index.html, sin instalar nada.
  • Publicar: sube la carpeta a cualquier servicio de páginas estáticas (Netlify, Vercel, GitHub Pages) y comparte la URL.

La carpeta no se guarda en Git (está en .gitignore): se genera cada vez.

Piezas por componente (para la skill 540)

npm run build:pieces && npm run check:pieces

Deja en pieces/ lo que la skill necesita para montar un HTML autocontenido sin este repo ni node_modules:

| Carpeta | Qué hay | | --- | --- | | server/ | Un módulo ESM por componente, con Preact (a través de preact/compat) dentro, para pre-renderizar en Node. runtime.js trae renderIsland, renderStatic y registryOf, y mantiene renderToString y renderToStaticMarkup para las charlas que ya los usaban. | | css/ | base.css (tokens, reset y DM Sans) y una hoja por componente. | | islands/ | runtime.js (Preact + hidratación) y un script por cada uno de los 14 componentes interactivos. | | fonts/ | DM Sans variable, subconjunto latino, con su licencia SIL OFL. | | manifest.json | Versión, la de Preact (preact; antes react), y por componente: su módulo, sus hojas en orden de carga su isla, si la tiene, y si lee los pasos de Steps (readsSteps). También el contrato de etiquetas: tags, phrasing y svg. | | render/ | El render de charlas: convierte un documento con etiquetas <rev-…> en un .html autocontenido. Corre con node, sin instalar nada ni red. core.mjs es la parte que no usa Node (validar y pintar), compartida con el runtime. | | runtime/ | El runtime del navegador: runtime.js pinta en la página una charla escrita con etiquetas, con las mismas comprobaciones y el mismo HTML que el render. El manifiesto y cada hoja de estilo (con DM Sans dentro) van como módulos JS, porque un artifact de claude.ai solo carga scripts de un CDN. |

Cómo funciona una isla (el contrato está en src/runtime/islands.ts): el componente se pinta en el servidor dentro de <ds-island> con sus props en JSON; en el navegador, runtime.js lo hidrata. El contenido estático que recibe como hijo va en <ds-slot> y Preact no lo toca, así que las islas que hay dentro se hidratan solas; si un slot se vuelve a montar en el cliente, el runtime hidrata las islas nuevas que trae. Lo que lee el contexto de Steps (Step, Count, Bars, Sheet, Schema, Share) entra en el árbol de la isla de Steps en vez de ir como slot. Dialog no es isla: se abre y se cierra con open y onClose, y una función no viaja en el JSON de las props; quien lo use desde una isla lo lleva dentro de su script. check:pieces monta una charla con Deck, Steps, Count, Carousel y Statements y comprueba en jsdom que todo hidrata sin errores.

Render de charlas

npm run render -- charla.rev.html            # escribe charla.html
node pieces/render/cli.mjs charla.rev.html   # lo mismo, con las piezas ya construidas
npm run test:render

El contrato de etiquetas, acordado con la pista B (el MCP), está en scripts/render/CONTRATO.md. El HTML sale con solo el CSS de los componentes usados, DM Sans y las imágenes incrustadas, y JavaScript solo si hay alguna isla. Si una etiqueta, un atributo o un valor no existe, falla y los lista todos.

El render en npm

Las piezas y el render viajan en el paquete @540deg/ds (carpeta pieces/, sin demo.html ni samples/), con el ejecutable 540-ds-render. prepack construye la librería y las piezas, y publish.yml pasa test:render y check:pieces antes de publicar. La skill 540-ds del toolkit lo usa con una versión fija, sin copiar nada en el plugin:

npx -y --package=@540deg/[email protected] 540-ds-render charla.rev.html             # escribe charla.html
npx -y --package=@540deg/[email protected] 540-ds-render charla.rev.html --lang en   # charla en inglés
npx -y --package=@540deg/[email protected] 540-ds-render --contract                  # el contrato de etiquetas
npx -y --package=@540deg/[email protected] 540-ds-render --tags GridItem rev-metric  # props de esas etiquetas (sin nombres: todas)
npx -y --package=@540deg/[email protected] 540-ds-render --version                   # versión del sistema

La primera vez necesita conexión para bajar el paquete; después npm lo guarda en caché y funciona sin red. Para que la skill use una versión nueva, se publica aquí y se cambia el número en la skill.

El runtime del navegador

Para claude.ai o donde no hay Node: la charla va dentro de un <script type="text/rev"> y la pinta el navegador al abrirla, cargando desde jsDelivr solo los componentes que usa. Si tiene errores, no pinta nada y enseña un panel con la lista, con línea y sugerencia, y un botón para copiarla. El formato está en scripts/render/CONTRATO.md; el render de Node acepta el mismo fichero.

npm run check:runtime   # abre charlas en Chromium y compara el runtime con el render, byte a byte

TalkTemplate no entra en las piezas: es una charla de ejemplo con fotos de muestra, no un componente que se rellene. La carpeta no se guarda en Git.

Usarlo en un proyecto React (paquete npm)

La librería se publica en npm como @540deg/ds. Trae todos los componentes del catálogo y TalkTemplate, con sus tipos de TypeScript. Necesita React 19 en el proyecto que la usa.

npm install @540deg/ds

Importa la hoja de estilos una vez, en la entrada de la app (main.tsx o el layout raíz), y los componentes donde los uses:

import '@540deg/ds/styles.css';
import { Deck, Slide, Text } from '@540deg/ds';
import type { DeckProps } from '@540deg/ds';
  • Una sola hoja: styles.css lleva los tokens, el reset y los estilos base (fondo, color y letra en html y body), DM Sans (la fuente va dentro del paquete, no hace falta Google Fonts) y los estilos de todos los componentes. Los componentes no importan CSS por su cuenta, así que funcionan con cualquier bundler y en el servidor.
  • Solo lo que usas: cada componente es un módulo aparte y el paquete está marcado sin efectos secundarios salvo el CSS, así que el bundler descarta lo que no importas. TalkTemplate lleva sus fotos de muestra dentro y solo pesan si lo importas.
  • Tipos: cada componente exporta sus Props (DeckProps, ButtonProps…) y sus listas de valores (BUTTON_VARIANTS…). Se resuelven con "moduleResolution": "bundler" en el tsconfig, que es lo que traen Vite y Next.
  • Tema: Deck pinta el tema oscuro o claro en su propio contenedor; fuera de un Deck, el tema claro es el de :root y el oscuro se activa con data-theme="dark" en un antepasado.
  • Normas: las charlas hechas con el paquete siguen las mismas normas (src/docs/normas-charlas.md): solo componentes del catálogo y sus props, sin CSS propio.

Publicar una versión

main solo acepta cambios por PR, así que la versión se sube en una rama y la etiqueta se crea después, sobre main:

  1. Desde main al día, abre una rama y sube la versión sin crear etiqueta (patch, minor o major):

    git checkout main && git pull
    git checkout -b release/vX.Y.Z
    npm version patch --no-git-tag-version
    git commit -am "Release X.Y.Z"
    git push -u origin release/vX.Y.Z
  2. Abre el PR contra main y mergéalo.

  3. Crea la etiqueta sobre main y súbela:

    git checkout main && git pull
    git tag vX.Y.Z && git push origin vX.Y.Z
  4. El flujo .github/workflows/publish.yml comprueba que la etiqueta coincide con la versión de package.json, pasa tipos, lint, SSR, el render y las piezas, construye la librería y las piezas y las publica en npm con provenance. Míralo en Actions → "Publish to npm" y comprueba con npm view @540deg/ds version.

Una versión publicada no se puede volver a publicar ni reutilizar su número: si algo sale mal, se arregla y se sube la siguiente.

Una versión de prueba (0.2.0-rc.0, con guion) se publica igual, pero con la etiqueta de npm next: latest, que es lo que instala npm install @540deg/ds, sigue en la última estable. jsDelivr la sirve por su número exacto.

No usa tokens: publica con Trusted Publishing de npm. En npmjs.com, @540deg/ds → Settings → Trusted Publisher tiene dado de alta este repositorio y el flujo publish.yml. Si se renombra el fichero del flujo o el repositorio, hay que cambiarlo también allí.

Para probar el paquete en local sin publicarlo:

npm run build:lib   # deja la librería en dist/
npm pack            # crea 540deg-ds-X.Y.Z.tgz, instalable con npm install ./ruta/al.tgz

Fuentes de verdad

  1. Este código.
  2. Las charlas anteriores (base-540.css, navegacion-540.js y su guía de estilos), de donde salen las piezas de presentación.
  3. El archivo de Figma «540 · Design System», de donde se copian las fichas de los componentes. Si Figma y el código discrepan, manda el código.

Licencia

El código está bajo Apache License 2.0. La licencia no da derechos sobre el nombre, el logo ni la identidad visual de 540, ni sobre las fotos de muestra: siguen siendo de 540 (ver NOTICE). DM Sans va con su propia licencia, SIL OFL 1.1.