repository·main·Indexed 41 days ago
https://github.com/juntossomosmais/atomiumThe official design system of Juntos Somos Mais, built with Web Components to provide reusable UI elements across React, Vue, and Vanilla JS. It includes a core component library, a dedicated icon system served via CDN, and a set of design tokens available as CSS variables, JavaScript objects, or JSON.
Elevation tokens in the Juntos Design System indicate the distance of interface elements from the surface, determining how their shadows appear. The system provides 8 elevation levels (0dp to 8dp). To achieve a natural shadow effect, each token utilizes overlapping shadows.
Additionally, the system provides zindex tokens to manage the stacking order of elements, which should be used in conjunction with elevation to maintain visual hierarchy.
Atomium is built using Web Components to ensure the design system remains highly portable and future-proof. This architectural choice addresses several key requirements for modern development:
Atomium uses transpiled wrappers for both React and Vue to solve inherent compatibility issues between Web Components and these frameworks.
Without these wrappers, developers face several Developer Experience (DX) hurdles:
SyntheticEvent, which is incompatible with the CustomEvent interface used by Web Components. Developers would otherwise need to manually attach event listeners.array or object types often require manual conversion to JSON strings to ensure compatibility with the Web Component's attributes.ref.array and object props require manual JSON conversion.ref.Atomium provides specialized packages (@juntossomosmais/atomium-react and @juntossomosmais/atomium-vue) that act as transpiled wrappers. These packages ensure seamless integration, proper event handling, and correct prop type passing, providing a native-like DX for both frameworks.
Atomium defines specific breakpoints used across projects to manage responsive layouts. Use these ranges to understand how the design adapts to different device sizes:
When developing or extending Atomium components, be aware that lifecycle hooks (connectedCallback, componentWillLoad, componentDidLoad, render) execute during server hydration. To prevent crashes in Node environments, follow these patterns:
window or document access: Use fallbacks for APIs like matchMedia which may not exist in the Node global scope.getComputedStyle or Popper.js instances) must be guarded.Build.isServer && !Build.isTesting rather than just Build.isServer. This ensures that while the code is skipped during SSR, it remains executable during Jest unit tests (where isServer and isTesting are both true).Example Guard Pattern:
if (Build.isServer && !Build.isTesting) {
// Skip server-only logic or browser-only initialization
}Atomium uses two different encapsulation strategies for Web Components to ensure they work correctly during Server-Side Rendering (SSR) and client-side hydration, specifically when used in frameworks like React (Next.js).
shadow: true)Components that require immediate interactivity and data propagation (like atom-input) use Shadow DOM (shadow: true).
<template shadowrootmode="open">). This allows the Stencil runtime to hydrate them reliably even when they are nested inside other Stencil components during SSR.scoped/light DOM)Components that render overlays (like atom-modal, atom-datetime, and atom-steps-modal) use Scoped/Light DOM encapsulation and are excluded from SSR.
body or ion-app). In Shadow DOM, <slot> is a virtual projection; if the slot element teleports away, the projected content disappears. Using light DOM ensures content travels with the teleported element.| Component Type | Encapsulation | SSR Strategy | Example |
|---|---|---|---|
| In-flow Interactive | shadow: true | Full SSR (DSD) | atom-input |
| Overlays/Teleports | scoped | Client-only | atom-modal, atom-datetime |
To ensure you inherit this encapsulation logic correctly, always consume the package via the @juntossomosmais/atomium/react/next barrel entry. This entry point automatically resolves overlays to their client-only versions.
Atomium uses a wrapper for Ionic Components (available in the @atomium/core package) to manage icons. This wrapper leverages Ionic's logic to fetch icon SVGs from a CDN and render them within the Shadow DOM.
This architecture provides two main benefits:
Atomium uses a hydrateModule (exported from @juntossomosmais/atomium/hydrate) to enable Server-Side Rendering.
When renderToString() is called in a Node environment, the library serializes components using Declarative Shadow DOM (DSD). This means the server returns HTML containing <template shadowrootmode="open"> tags. This allows the browser to render the component's shadow DOM immediately upon receiving the HTML, before the client-side JavaScript has even loaded, effectively eliminating FOUC and layout shifts.
Because Atomium includes @ionic/core internals, even Ionic components (ion-*) inside Atomium shadow roots are fully rendered on the server with their styles and modes resolved.
Atomium contextual colors follow a strict WCAG 2.1 AA contrast contract to ensure accessibility. Each color step has a specific intended use case:
-dark-1: High emphasis. At least 7:1 against white. Use for emphasis, hover, and pressed states.-regular: The default step. At least 4.5:1 against white AND at least 4.5:1 against its own -light-2. Use for text, icons, borders, or as a fill with white text.-light-1: The light step. At least 4.5:1 as a fill carrying dark text, AND at least 4.5:1 as text/icon on a dark surface. Use on dark surfaces.-light-2: The soft surface. Use as a background, not as a foreground color.Recommendation: Use -regular by default for ordinary text, icons, or borders. Only use -dark-1 when higher emphasis is required.
Atomium React components are automatically generated wrappers around core Web Components using @stencil/react-output-target. This architecture ensures: