@aiaiai-pt/design-system 0.8.3 → 0.9.0

package/components/AppFrame.svelte

@@ -0,0 +1,75 @@
+<!--
+  @component AppFrame
+
+  The locked public site-shell scaffold: skip-link → header → a single `<main>`
+  landmark → footer, in fixed DOM (= reading) order. This is the
+  accessibility-by-construction frame for the citizen portal — every page is
+  wrapped in exactly one AppFrame, guaranteeing one main landmark, a working
+  skip target, and linear reading order (ARTE Silver / WCAG 1.3.2, 2.4.1).
+  Structure is frozen and conformance-checkable; only brand tokens vary per
+  tenant via `data-theme`.
+
+  `header` and `footer` are slots so a tenant composes `SiteHeader` / `SiteFooter`
+  with its own brand + nav; the page content is the default `children`.
+
+  @example
+  <AppFrame>
+    {#snippet header()}<SiteHeader>…</SiteHeader>{/snippet}
+    {#snippet footer()}<SiteFooter>…</SiteFooter>{/snippet}
+    <PageContainer>{@render page()}</PageContainer>
+  </AppFrame>
+-->
+<script>
+  import SkipLink from "./SkipLink.svelte";
+
+  let {
+    /** @type {string} id of the main landmark (skip-link target). */
+    mainId = "main",
+    /** @type {string} */
+    class: className = "",
+    /** @type {import('svelte').Snippet | undefined} Override the default skip link (e.g. localized). */
+    skipLink = undefined,
+    /** @type {import('svelte').Snippet | undefined} Site banner (compose `SiteHeader`). */
+    header = undefined,
+    /** @type {import('svelte').Snippet | undefined} Site footer (compose `SiteFooter`). */
+    footer = undefined,
+    /** @type {import('svelte').Snippet | undefined} Page content (rendered inside `<main>`). */
+    children = undefined,
+    ...rest
+  } = $props();
+</script>
+
+<div class="app-frame {className}" {...rest}>
+  {#if skipLink}{@render skipLink()}{:else}<SkipLink href={`#${mainId}`} />{/if}
+
+  {#if header}{@render header()}{/if}
+
+  <!-- Single main landmark + focus target for the skip link. tabindex=-1 so
+       the skip link can move focus here without making it tabbable otherwise. -->
+  <main id={mainId} tabindex="-1" class="app-frame-main">
+    {#if children}{@render children()}{/if}
+  </main>
+
+  {#if footer}{@render footer()}{/if}
+</div>
+
+<style>
+  .app-frame {
+    display: flex;
+    flex-direction: column;
+    min-height: 100vh;
+    min-height: 100dvh;
+    background: var(--color-surface);
+    color: var(--color-text);
+  }
+
+  /* Main grows to push the footer down; the focus target shows no outline box
+     (focus is programmatic via the skip link, not a visible widget). */
+  .app-frame-main {
+    flex: 1 0 auto;
+  }
+
+  .app-frame-main:focus {
+    outline: none;
+  }
+</style>

package/components/AppFrame.svelte.d.ts

@@ -0,0 +1,42 @@
+export default AppFrame;
+type AppFrame = {
+    $on?(type: string, callback: (e: any) => void): () => void;
+    $set?(props: Partial<$$ComponentProps>): void;
+};
+/**
+ * AppFrame
+ *
+ * The locked public site-shell scaffold: skip-link → header → a single `<main>`
+ * landmark → footer, in fixed DOM (= reading) order. This is the
+ * accessibility-by-construction frame for the citizen portal — every page is
+ * wrapped in exactly one AppFrame, guaranteeing one main landmark, a working
+ * skip target, and linear reading order (ARTE Silver / WCAG 1.3.2, 2.4.1).
+ * Structure is frozen and conformance-checkable; only brand tokens vary per
+ * tenant via `data-theme`.
+ *
+ * `header` and `footer` are slots so a tenant composes `SiteHeader` / `SiteFooter`
+ * with its own brand + nav; the page content is the default `children`.
+ *
+ * @example
+ * <AppFrame>
+ *   {#snippet header()}<SiteHeader>…</SiteHeader>{/snippet}
+ *   {#snippet footer()}<SiteFooter>…</SiteFooter>{/snippet}
+ *   <PageContainer>{@render page()}</PageContainer>
+ * </AppFrame>
+ */
+declare const AppFrame: import("svelte").Component<{
+    mainId?: string;
+    class?: string;
+    skipLink?: any;
+    header?: any;
+    footer?: any;
+    children?: any;
+} & Record<string, any>, {}, "">;
+type $$ComponentProps = {
+    mainId?: string;
+    class?: string;
+    skipLink?: any;
+    header?: any;
+    footer?: any;
+    children?: any;
+} & Record<string, any>;

package/components/ContentBlock.svelte

@@ -0,0 +1,100 @@
+<!--
+  @component ContentBlock
+
+  Prose container for documentation / legal / content pages (privacy, terms,
+  accessibility, regulamento — the `content` page template). Applies readable
+  measure + typographic rhythm to long-form content, with an optional title
+  and a version/date badge slot.
+
+  SECURITY: ContentBlock only STYLES its children — it does not parse or
+  sanitise. A consumer rendering operator-authored markdown/HTML MUST sanitise
+  before injecting it (XSS); pass the sanitised result as `children`.
+
+  @example
+  <ContentBlock title="Privacy Policy">
+    {#snippet badge()}<Badge>v3 · updated 2026-05-01</Badge>{/snippet}
+    {@html sanitizedHtml}
+  </ContentBlock>
+-->
+<script>
+  let {
+    /** @type {string} Page title (rendered as h1 — keep one per page). */
+    title = "",
+    /** @type {1 | 2} Heading level for `title`. */
+    headingLevel = 1,
+    /** @type {string} */
+    class: className = "",
+    /** @type {import('svelte').Snippet | undefined} Version / date badge. */
+    badge = undefined,
+    /** @type {import('svelte').Snippet | undefined} The (pre-sanitised) prose. */
+    children = undefined,
+    ...rest
+  } = $props();
+</script>
+
+<article class="content-block {className}" {...rest}>
+  {#if title}
+    <header class="content-block-head">
+      <svelte:element this={`h${headingLevel}`} class="content-block-title">{title}</svelte:element>
+      {#if badge}<div class="content-block-badge">{@render badge()}</div>{/if}
+    </header>
+  {/if}
+  <div class="content-block-prose">
+    {#if children}{@render children()}{/if}
+  </div>
+</article>
+
+<style>
+  .content-block {
+    width: 100%;
+    max-width: var(--content-width-narrow);
+    margin-inline: auto;
+    padding: var(--space-2xl) var(--content-padding-x);
+  }
+
+  .content-block-head {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: baseline;
+    gap: var(--space-sm);
+    margin-bottom: var(--space-lg);
+  }
+
+  .content-block-title {
+    margin: 0;
+    font-family: var(--type-heading-lg-font);
+    font-size: var(--type-heading-lg-size);
+    color: var(--color-text);
+  }
+
+  /* Long-form rhythm. Scoped to descendants since prose is consumer-injected
+     (:global needed — these elements aren't in this component's own markup). */
+  .content-block-prose {
+    font-family: var(--type-body-font);
+    font-size: var(--type-body-size);
+    color: var(--color-text);
+    line-height: 1.6;
+  }
+
+  .content-block-prose :global(h2) {
+    font-family: var(--type-heading-font);
+    font-size: var(--type-heading-size);
+    margin: var(--space-xl) 0 var(--space-sm);
+  }
+
+  .content-block-prose :global(h3) {
+    font-family: var(--type-heading-sm-font);
+    font-size: var(--type-heading-sm-size);
+    margin: var(--space-lg) 0 var(--space-xs);
+  }
+
+  .content-block-prose :global(p),
+  .content-block-prose :global(ul),
+  .content-block-prose :global(ol) {
+    margin: 0 0 var(--space-md);
+  }
+
+  .content-block-prose :global(a) {
+    color: var(--color-accent);
+  }
+</style>

package/components/ContentBlock.svelte.d.ts

@@ -0,0 +1,37 @@
+export default ContentBlock;
+type ContentBlock = {
+    $on?(type: string, callback: (e: any) => void): () => void;
+    $set?(props: Partial<$$ComponentProps>): void;
+};
+/**
+ * ContentBlock
+ *
+ * Prose container for documentation / legal / content pages (privacy, terms,
+ * accessibility, regulamento — the `content` page template). Applies readable
+ * measure + typographic rhythm to long-form content, with an optional title
+ * and a version/date badge slot.
+ *
+ * SECURITY: ContentBlock only STYLES its children — it does not parse or
+ * sanitise. A consumer rendering operator-authored markdown/HTML MUST sanitise
+ * before injecting it (XSS); pass the sanitised result as `children`.
+ *
+ * @example
+ * <ContentBlock title="Privacy Policy">
+ *   {#snippet badge()}<Badge>v3 · updated 2026-05-01</Badge>{/snippet}
+ *   {@html sanitizedHtml}
+ * </ContentBlock>
+ */
+declare const ContentBlock: import("svelte").Component<{
+    title?: string;
+    headingLevel?: number;
+    class?: string;
+    badge?: any;
+    children?: any;
+} & Record<string, any>, {}, "">;
+type $$ComponentProps = {
+    title?: string;
+    headingLevel?: number;
+    class?: string;
+    badge?: any;
+    children?: any;
+} & Record<string, any>;

package/components/Hero.svelte

@@ -0,0 +1,87 @@
+<!--
+  @component Hero
+
+  Landing / page hero. Renders the page's primary heading (an `<h1>` by
+  default — keep exactly one per page for the single-H1 a11y contract), an
+  optional subtitle, and an actions slot. Use at the top of `landing` and
+  `service-flow` page templates.
+
+  @example
+  <Hero title="Report a problem in Valongo" subtitle="Potholes, lighting, waste — in two minutes.">
+    {#snippet actions()}<Button href="/report">Start a report</Button>{/snippet}
+  </Hero>
+
+  @example Custom heading level (when the hero is not the page's H1)
+  <Hero title="Latest consultations" headingLevel={2} />
+-->
+<script>
+  let {
+    /** @type {string} */
+    title = "",
+    /** @type {string} */
+    subtitle = "",
+    /** @type {1 | 2 | 3} Heading level for `title` — keep one h1 per page. */
+    headingLevel = 1,
+    /** @type {string} */
+    class: className = "",
+    /** @type {import('svelte').Snippet | undefined} Title override (rich content). */
+    children = undefined,
+    /** @type {import('svelte').Snippet | undefined} Call-to-action buttons. */
+    actions = undefined,
+    ...rest
+  } = $props();
+</script>
+
+<section class="hero {className}" {...rest}>
+  <div class="hero-inner">
+    {#if children}
+      {@render children()}
+    {:else if title}
+      <svelte:element this={`h${headingLevel}`} class="hero-title">{title}</svelte:element>
+    {/if}
+    {#if subtitle}
+      <p class="hero-subtitle">{subtitle}</p>
+    {/if}
+    {#if actions}
+      <div class="hero-actions">{@render actions()}</div>
+    {/if}
+  </div>
+</section>
+
+<style>
+  .hero {
+    background: var(--color-surface);
+  }
+
+  .hero-inner {
+    width: 100%;
+    max-width: var(--content-width-wide);
+    margin-inline: auto;
+    padding: var(--space-3xl) var(--content-padding-x);
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-md);
+  }
+
+  .hero-title {
+    margin: 0;
+    font-family: var(--type-display-font);
+    font-size: var(--type-display-size);
+    color: var(--color-text);
+  }
+
+  .hero-subtitle {
+    margin: 0;
+    max-width: var(--content-width-narrow);
+    font-family: var(--type-body-font);
+    font-size: var(--type-body-size);
+    color: var(--color-text-secondary);
+  }
+
+  .hero-actions {
+    display: flex;
+    flex-wrap: wrap;
+    gap: var(--space-sm);
+    margin-top: var(--space-sm);
+  }
+</style>

package/components/Hero.svelte.d.ts

@@ -0,0 +1,37 @@
+export default Hero;
+type Hero = {
+    $on?(type: string, callback: (e: any) => void): () => void;
+    $set?(props: Partial<$$ComponentProps>): void;
+};
+/**
+ * Hero
+ *
+ * Landing / page hero. Renders the page's primary heading (an `<h1>` by
+ * default — keep exactly one per page for the single-H1 a11y contract), an
+ * optional subtitle, and an actions slot. Use at the top of `landing` and
+ * `service-flow` page templates.
+ *
+ * @example
+ * <Hero title="Report a problem in Valongo" subtitle="Potholes, lighting, waste — in two minutes.">
+ *   {#snippet actions()}<Button href="/report">Start a report</Button>{/snippet}
+ * </Hero>
+ *
+ * @example Custom heading level (when the hero is not the page's H1)
+ * <Hero title="Latest consultations" headingLevel={2} />
+ */
+declare const Hero: import("svelte").Component<{
+    title?: string;
+    subtitle?: string;
+    headingLevel?: number;
+    class?: string;
+    children?: any;
+    actions?: any;
+} & Record<string, any>, {}, "">;
+type $$ComponentProps = {
+    title?: string;
+    subtitle?: string;
+    headingLevel?: number;
+    class?: string;
+    children?: any;
+    actions?: any;
+} & Record<string, any>;

package/components/Link.svelte

@@ -0,0 +1,100 @@
+<!--
+  @component Link
+
+  A text hyperlink. Two variants, following the Carbon convention:
+   - `inline` (default): used inside sentences/prose — always underlined so it's
+     distinguishable from surrounding text.
+   - `standalone`: used on its own after content (lists, CTAs, footers) —
+     underlined only on hover/focus.
+
+  Accessibility:
+   - A link with no (or empty) `href` is NOT a link — it renders a
+     non-interactive `<span aria-current="page">` (the canonical "you are here"
+     treatment) instead of a keyboard-trap `<a>` with no destination.
+   - `external` adds `target="_blank"` + `rel="noopener noreferrer"`.
+   - Visible focus ring on `:focus-visible`.
+
+  @example Inline (prose)
+  Read our <Link href="/info/privacy">privacy policy</Link>.
+
+  @example Standalone CTA
+  <Link href="/report" variant="standalone">Report a problem</Link>
+
+  @example Current page (no href → rendered as non-interactive)
+  <Link current>Home</Link>
+-->
+<script>
+  let {
+    /** @type {string | undefined} Destination. Falsy → rendered as a non-interactive span. */
+    href = undefined,
+    /** @type {'inline' | 'standalone'} */
+    variant = "inline",
+    /** @type {boolean} Marks the current page (`aria-current="page"`). */
+    current = false,
+    /** @type {boolean} Open in a new tab with safe rel. */
+    external = false,
+    /** @type {string} */
+    class: className = "",
+    /** @type {import('svelte').Snippet | undefined} */
+    children = undefined,
+    ...rest
+  } = $props();
+
+  const isLink = $derived(typeof href === "string" && href.length > 0);
+  const externalAttrs = $derived(
+    external ? { target: "_blank", rel: "noopener noreferrer" } : {},
+  );
+</script>
+
+{#if isLink}
+  <a
+    {href}
+    class="link link-{variant} {className}"
+    aria-current={current ? "page" : undefined}
+    {...externalAttrs}
+    {...rest}
+  >
+    {#if children}{@render children()}{/if}
+  </a>
+{:else}
+  <!-- No destination → not a link. Non-interactive, still announces "current". -->
+  <span class="link link-{variant} link-static {className}" aria-current={current ? "page" : undefined} {...rest}>
+    {#if children}{@render children()}{/if}
+  </span>
+{/if}
+
+<style>
+  .link {
+    color: var(--color-accent);
+    border-radius: var(--radius-sm);
+  }
+
+  .link-inline {
+    text-decoration: underline;
+    text-underline-offset: 0.15em;
+  }
+
+  .link-standalone {
+    text-decoration: none;
+  }
+  .link-standalone:hover {
+    text-decoration: underline;
+    text-underline-offset: 0.15em;
+  }
+
+  a.link:hover {
+    color: var(--color-accent-hover);
+  }
+
+  a.link:focus-visible {
+    outline: var(--focus-ring-width) solid var(--focus-ring-color);
+    outline-offset: var(--focus-ring-offset);
+  }
+
+  /* Non-interactive (current/no-href): inherit text colour, no affordance. */
+  .link-static {
+    color: var(--color-text);
+    text-decoration: none;
+    cursor: default;
+  }
+</style>

package/components/Link.svelte.d.ts

@@ -0,0 +1,46 @@
+export default Link;
+type Link = {
+    $on?(type: string, callback: (e: any) => void): () => void;
+    $set?(props: Partial<$$ComponentProps>): void;
+};
+/**
+ * Link
+ *
+ * A text hyperlink. Two variants, following the Carbon convention:
+ *  - `inline` (default): used inside sentences/prose — always underlined so it's
+ *    distinguishable from surrounding text.
+ *  - `standalone`: used on its own after content (lists, CTAs, footers) —
+ *    underlined only on hover/focus.
+ *
+ * Accessibility:
+ *  - A link with no (or empty) `href` is NOT a link — it renders a
+ *    non-interactive `<span aria-current="page">` (the canonical "you are here"
+ *    treatment) instead of a keyboard-trap `<a>` with no destination.
+ *  - `external` adds `target="_blank"` + `rel="noopener noreferrer"`.
+ *  - Visible focus ring on `:focus-visible`.
+ *
+ * @example Inline (prose)
+ * Read our <Link href="/info/privacy">privacy policy</Link>.
+ *
+ * @example Standalone CTA
+ * <Link href="/report" variant="standalone">Report a problem</Link>
+ *
+ * @example Current page (no href → rendered as non-interactive)
+ * <Link current>Home</Link>
+ */
+declare const Link: import("svelte").Component<{
+    href?: any;
+    variant?: string;
+    current?: boolean;
+    external?: boolean;
+    class?: string;
+    children?: any;
+} & Record<string, any>, {}, "">;
+type $$ComponentProps = {
+    href?: any;
+    variant?: string;
+    current?: boolean;
+    external?: boolean;
+    class?: string;
+    children?: any;
+} & Record<string, any>;

package/components/ServiceNavigation.svelte

@@ -0,0 +1,160 @@
+<!--
+  @component ServiceNavigation
+
+  Primary site navigation for the public portal, modelled on the GOV.UK
+  "Service navigation" and Designers Italia header-nav patterns (the citizen /
+  PA gold standard). Data-driven: it owns its `<a>` markup (rendered from
+  `items`), so it styles its own links — no magic descendant styling of
+  consumer anchors.
+
+  Accessibility:
+   - `<nav aria-label>` landmark; the current item carries `aria-current="page"`.
+   - Below `--breakpoint` the list collapses behind a toggle button with
+     `aria-expanded` + `aria-controls` (WCAG-friendly disclosure).
+   - Empty `items` renders NOTHING — never an empty nav landmark.
+   - Toggle + links have visible focus rings.
+
+  @example
+  <ServiceNavigation
+    label="Primary"
+    items={[
+      { href: "/report", label: "Report a problem" },
+      { href: "/track", label: "Track a report", current: true },
+      { href: "/info/privacy", label: "Privacy" },
+    ]}
+  >
+    {#snippet menuIcon()}<MenuIcon />{/snippet}
+  </ServiceNavigation>
+-->
+<script>
+  let {
+    /** @type {Array<{ href: string, label: string, current?: boolean }>} */
+    items = [],
+    /** @type {string} aria-label for the nav landmark (localize it). */
+    label = "Primary",
+    /** @type {string} id linking the toggle button to the menu (unique per page). */
+    menuId = "service-navigation-menu",
+    /** @type {string} Visible label for the mobile toggle (localize it). */
+    toggleLabel = "Menu",
+    /** @type {string} */
+    class: className = "",
+    /** @type {import('svelte').Snippet | undefined} Icon for the mobile toggle. */
+    menuIcon = undefined,
+    ...rest
+  } = $props();
+
+  let open = $state(false);
+</script>
+
+{#if items.length > 0}
+  <nav class="service-nav {className}" aria-label={label} {...rest}>
+    <button
+      type="button"
+      class="service-nav-toggle"
+      aria-expanded={open}
+      aria-controls={menuId}
+      onclick={() => (open = !open)}
+    >
+      {#if menuIcon}{@render menuIcon()}{/if}
+      <span class="service-nav-toggle-label">{toggleLabel}</span>
+    </button>
+
+    <ul id={menuId} class="service-nav-list" class:open>
+      {#each items as item (item.href)}
+        <li class="service-nav-item">
+          <a
+            href={item.href}
+            class="service-nav-link"
+            aria-current={item.current ? "page" : undefined}
+          >
+            {item.label}
+          </a>
+        </li>
+      {/each}
+    </ul>
+  </nav>
+{/if}
+
+<style>
+  .service-nav {
+    display: flex;
+    align-items: center;
+  }
+
+  /* Toggle hidden on wide viewports; the list is a horizontal row. */
+  .service-nav-toggle {
+    display: none;
+    align-items: center;
+    gap: var(--space-2xs);
+    padding: var(--space-2xs) var(--space-sm);
+    border: 1px solid var(--color-border);
+    border-radius: var(--radius-md);
+    background: var(--color-surface);
+    color: var(--color-text);
+    font-family: var(--type-label-font);
+    font-size: var(--type-label-size);
+    cursor: pointer;
+  }
+  .service-nav-toggle:focus-visible,
+  .service-nav-link:focus-visible {
+    outline: var(--focus-ring-width) solid var(--focus-ring-color);
+    outline-offset: var(--focus-ring-offset);
+  }
+
+  .service-nav-list {
+    display: flex;
+    align-items: center;
+    gap: var(--space-2xs);
+    margin: 0;
+    padding: 0;
+    list-style: none;
+  }
+
+  .service-nav-link {
+    display: block;
+    padding: var(--space-2xs) var(--space-sm);
+    border-radius: var(--radius-md);
+    color: var(--color-text-secondary);
+    text-decoration: none;
+    font-family: var(--type-label-font);
+    font-size: var(--type-label-size);
+  }
+  .service-nav-link:hover {
+    color: var(--color-text);
+    background: var(--color-surface-tertiary);
+  }
+  /* Current page: emphasized text + an accent underline bar (GOV.UK pattern). */
+  .service-nav-link[aria-current="page"] {
+    color: var(--color-text);
+    font-weight: var(--raw-font-weight-semibold);
+    box-shadow: inset 0 -3px 0 0 var(--color-accent);
+  }
+
+  /* Mobile: button shows, list collapses behind it. */
+  @media (max-width: 47.99rem) {
+    .service-nav {
+      position: relative;
+    }
+    .service-nav-toggle {
+      display: inline-flex;
+    }
+    .service-nav-list {
+      display: none;
+      position: absolute;
+      top: calc(100% + var(--space-2xs));
+      inset-inline-end: 0;
+      flex-direction: column;
+      align-items: stretch;
+      min-width: 12rem;
+      padding: var(--space-2xs);
+      background: var(--color-surface);
+      border: 1px solid var(--color-border);
+      border-radius: var(--radius-md);
+      box-shadow: var(--shadow-md);
+      z-index: 50;
+    }
+    .service-nav-list.open {
+      display: flex;
+    }
+  }
+</style>