Cómo crear un producto

Los cinco roles

• --arche-color-brand Arche #ffffff example #e98950 El color de marca: el sigilo en su versión de color, en el favicon y los íconos de app. En la cabecera la marca va en blanco.
• --arche-color-link Arche #ffffff example #e98950 Links dentro del texto y botones de tipo link.
• --arche-color-selected Arche #ffffff example #e98950 Casillas, pestañas, switches y paginación marcados. Su fondo suave, selected-soft, es el tinte del acento: la fila elegida de una tabla.
• --arche-color-focus Arche #ffffff example #e98950 Anillo de foco de todos los controles.
• --arche-color-quote Arche #ffffff example #e98950 La regla de las citas en la prosa (Prose). Es decorativa, pero el build la mide como el foco: 3:1 contra el fondo y las tres capas.
• --arche-color-primary Arche #ffffff example #ffffff · no sigue al acento Acción principal. Blanca siempre, también en los productos.

El detalle de cada rol, con su contraste, está en Fundamentos · Acento y roles.

{	"name": "example",	"accent": "#d4763c"}

Después, en Arche:

npm run tokens        # normaliza el acento y genera products/example.cssnpm run tokens:check  # recetas, salidas y contraste en orden: sale con código 0

1. Lee la semilla como color CSS (hex, rgb(), oklch()…) y la pasa a OKLCH. Tiene que ser opaca.
2. Si su croma es menor que 0,03, la semilla es un gris: el acento pasa a ser el blanco, como en Arche.
3. Lleva la luminosidad al rango entre 0,72 y 0,84. El piso es el que pasa AA como texto en todos los tonos sobre el fondo más exigente, press sobre surface-overlay.
4. Limita el croma a 0,2 y conserva el tono: el acento sigue siendo el color que eligió el producto.
5. Si el color no entra en sRGB, baja el croma hasta que entre y elige el hex más cercano que siga dentro de las reglas.
6. Compara su tono con los cuatro estados y avisa si queda a menos de 28° de alguno.

Aviso: Producto «example»: el tono del acento #e98950 (49.88°) está a 25.88° de danger (mínimo 28°). Un link o una selección podrían leerse como un estado.Aviso: Producto «hermes»: el tono del acento #e98950 (49.88°) está a 25.88° de danger (mínimo 28°). Un link o una selección podrían leerse como un estado.Escrito src/lib/styles/products/example.cssEscrito src/lib/tokens/resolved.jsonTokens generados. 1040 pares de contraste verificados, 0 fallas.

El CSS generado, src/lib/styles/products/example.css, solo redefine la familia del acento bajo [data-product="example"]. Los roles se recalculan solos en ese elemento, porque tokens.css los declara para :root y para cada [data-product]. No se edita a mano.

/* Archivo generado: no editar. Fuente: src/lib/tokens/tokens.json (npm run tokens). *//* Producto «example»: acento #d4763c normalizado a #e98950.   Aviso: el tono del acento está a 25.88° de danger. */[data-product='example'] {	--arche-color-accent: #e98950;	--arche-color-accent-hover: #ee9d6e;	--arche-color-accent-soft: #2b211f;	--arche-color-accent-border: #674231;	--arche-color-accent-tint: rgb(233 137 80 / 0.07);}

npx sv create example --template minimal --types ts --no-add-ons --install npmcd examplenpm install @archeblack/ui

El package.json del producto queda con esta dependencia. El ^ fija la versión menor mientras Arche esté en 0.x: npm update trae los arreglos y los productos nuevos, y un cambio que rompe algo sube la versión menor y se instala a propósito, con @latest.

"@archeblack/ui": "^0.1.0"

npm update @archeblack/ui     # la última versión compatible con el rango de package.jsonnpm install @archeblack/ui@latest   # la última publicada, aunque cambie la versión menor

# En Arche-DS: empaqueta la versión local en archeblack-ui-0.1.0.tgz, sin publicarlanpm pack# En el producto, con las dos carpetas una al lado de la otranpm install ../Arche-DS/archeblack-ui-0.1.0.tgz

import '@archeblack/ui/fonts.css';import '@archeblack/ui/tokens.css';import '@archeblack/ui/base.css';import '@archeblack/ui/products/example.css';import './layout.css';

1. fonts.css, opcional: Archivo, Piazzolla e IBM Plex Mono autoalojadas. Si el producto ya carga las fuentes, se omite.
2. tokens.css: todas las variables --arche-* en :root y los roles, que se recalculan en cada elemento con data-product.
3. base.css: el documento (fondo, texto, margen del body, selección, foco, el link para saltar al contenido y movimiento reducido), en la capa arche.base.
4. products/example.css: la familia del acento bajo [data-product="example"]. Le gana a tokens.css por especificidad, no por orden: tokens.css declara el acento con :where(:root, [data-product]), que no pesa nada, y el selector de atributo del producto pesa más. Que vaya después es una convención: se lee en el orden en que se aplica.
5. layout.css, los estilos propios del producto: al final y sin capa, así ganan donde el producto lo decide.

npx sv add tailwindcss="plugins:none" --install npm

src/routes/layout.css pasa a cargar Arche. En el layout, los cuatro imports de Arche se van y layout.css queda como el único import de estilos: theme.css tiene que pasar por Tailwind, por eso va ahí y no en el layout. Los estilos propios del producto siguen debajo de estos imports.

@import 'tailwindcss';@import '@archeblack/ui/fonts.css';@import '@archeblack/ui/tokens.css';@import '@archeblack/ui/theme.css';@import '@archeblack/ui/base.css';@import '@archeblack/ui/products/example.css';

En src/app.html se suma el orden de capas, justo antes de %sveltekit.head%; el resto queda como arriba:

<style>	@layer properties, theme, base, arche, components, utilities;</style>%sveltekit.head%

El orden de capas @layer properties, theme, base, arche, components, utilities; deja a Arche después del reset de Tailwind (base) y antes de las utilidades: un class="px-6" sobre un Button gana, y el reset no le quita el fondo. El orden lo fija la primera vez que aparece cada capa, y SvelteKit puede enlazar el CSS de un componente antes que layout.css; por eso la declaración va en app.html, antes que cualquier hoja. Sin ella, en un build de producción, el reset de Tailwind le borró el fondo y el borde al botón secundario. properties es la capa que Tailwind emite primero.

• Un link para saltar al contenido, el primer elemento de la página: <a class="arche-skip-link" href="#content">Ir al contenido</a>. base.css lo oculta hasta que recibe el foco, y lleva al <main id="content"> del AppShell.
• Un TooltipProvider que envuelve toda la app: comparte el retardo entre tooltips vecinos.
• Un Toaster: monta las regiones vivas desde el principio, y cualquier página llama a toast().
• Un AppShell con product="Example": la marca es el nombre del producto, solo y en blanco, en la voz del logotipo (un producto con sigilo pasa mark y muestra su logotipo). En pantallas de menos de 48 rem la navegación pasa a un panel.

<script lang="ts">	import '@archeblack/ui/fonts.css';	import '@archeblack/ui/tokens.css';	import '@archeblack/ui/base.css';	import '@archeblack/ui/products/example.css';	import './layout.css';	import { page } from '$app/state';	import { resolve } from '$app/paths';	import favicon from '$lib/assets/favicon.svg';	import { AppShell, AppShellLink, Toaster, TooltipProvider } from '@archeblack/ui';	let { children } = $props();	const links = [		{ href: resolve('/'), label: 'Mensajes' },		{ href: resolve('/ajustes'), label: 'Ajustes' }	];</script><svelte:head>	<link rel="icon" href={favicon} /></svelte:head><!-- Lo primero de la página: salta al <main id="content"> del AppShell. --><a class="arche-skip-link" href="#content">Ir al contenido</a><TooltipProvider>	<AppShell product="Example" homeHref={resolve('/')} sticky>		{#snippet navigation()}			{#each links as link (link.href)}				<AppShellLink href={link.href} current={page.url.pathname === link.href}>					{link.label}				</AppShellLink>			{/each}		{/snippet}		{@render children()}	</AppShell>	<Toaster /></TooltipProvider>

/* Estilos propios de Example. Van después de Arche y solo usan clases propias. */.page {	display: grid;	gap: var(--arche-spacing-6);	max-width: 40rem;	padding: var(--arche-spacing-8) var(--arche-spacing-6);}.page h1 {	margin: 0;	font: var(--arche-typography-heading);	font-stretch: var(--arche-typography-heading-font-width);	letter-spacing: var(--arche-typography-heading-letter-spacing);	text-transform: var(--arche-typography-heading-text-transform);	color: var(--arche-color-text-strong);}.page p {	margin: 0;	color: var(--arche-color-text-muted);}.page__form {	display: grid;	gap: var(--arche-spacing-4);}.page__actions {	display: flex;	gap: var(--arche-spacing-2);}

<script lang="ts">	import { Button, Field, Input, Tooltip, toast } from '@archeblack/ui';	import { IconSend, IconX } from '@archeblack/ui/icons';	let to = $state('');	let error = $state('');	function send(event: SubmitEvent) {		event.preventDefault();		if (!to.includes('@')) {			error = 'Escribe un correo, por ejemplo ana@ejemplo.com.';			return;		}		error = '';		toast({ title: 'Mensaje enviado', description: to, variant: 'success' });		to = '';	}</script><svelte:head>	<title>Mensajes · Example</title></svelte:head><div class="page">	<h1>Mensajes</h1>	<p>Escribe a quién le llega el aviso. Example lo envía al instante.</p>	<form class="page__form" novalidate onsubmit={send}>		<Field label="Destinatario" hint="Un correo por envío." {error}>			<Input type="email" autocomplete="email" bind:value={to} />		</Field>		<div class="page__actions">			<Button type="submit" variant="primary" iconStart={IconSend}>Enviar</Button>			<Tooltip content="Vaciar el campo">				{#snippet trigger(props)}					<Button						{...props}						variant="ghost"						icon={IconX}						aria-label="Vaciar el campo"						onclick={() => (to = '')}					/>				{/snippet}			</Tooltip>		</div>	</form></div>

<script lang="ts">	import { Switch } from '@archeblack/ui';	let digest = $state(true);</script><svelte:head>	<title>Ajustes · Example</title></svelte:head><div class="page">	<h1>Ajustes</h1>	<Switch		bind:checked={digest}		label="Resumen diario"		description="Un correo a las 9:00 con los mensajes del día anterior."	/></div>

npm run dev la levanta; npm run check y npm run build pasan sin errores. El build muestra un aviso de tiempos, [PLUGIN_TIMINGS]: Vite avisa cuando los plugins se llevan la mayor parte del tiempo del build. No es un error ni cambia el resultado. Parte de ese tiempo viene de @archeblack/ui/icons, un barril que reexporta todo Tabler: para encontrar los íconos que se importan, Vite compila los más de 6.000 componentes del paquete, y el build tarda unas tres veces más que con los íconos importados de a uno. El resultado solo incluye los íconos importados.

• Todo nivel de texto, cada estado y el acento como texto (accent, accent-hover, link): 4,5:1 como mínimo contra el fondo, las tres superficies, hover y press compuestos sobre cada una y los fondos suaves.
• El texto sobre el acento, sobre el primario y sobre la selección: 4,5:1.
• Foco, selección y los bordes de los controles (border-control y su hover): 3:1 contra el fondo y las tres superficies.
• Que cada $value de tokens.json coincida con su receta y que los CSS generados, resolved.json y los CSS de producto estén al día (sin archivos de productos que ya no existen).

Link, el peor fondo (press sobre surface-overlay)

4,97:1 · mínimo 4,50:1

Foco, el peor fondo (surface-overlay)

6,68:1 · mínimo 3,00:1

Selección, el peor fondo (surface-overlay)

6,68:1 · mínimo 3,00:1

Los números son del producto example. Todo lo que el producto pinte fuera de los tokens queda fuera del chequeo.