Sistema di design Singapore Government.

Sistema di design Singapore Government Scegli la famiglia SGDS attuale

Componenti web e pagine Bootstrap precedenti

SGDS v 3 usa @govtechsg/sgds-web-component. I suoi custom elements, i token del tema e l’integrazione attuale delle utility seguono un percorso d’implementazione diverso rispetto al vecchio foglio di stile @govtechsg/sgds Bootstrap. Non combinare le istruzioni JavaScript di v 2 con i tag di v 3 aspettandoti che i nuovi controlli si inizializzino.

L’esempio usa il bundle browser effettivo 3.29.0 per registrare i controlli di quantità e i pulsanti. Presenta un pianificatore originale per un laboratorio comunitario, senza intestazione né dichiarazioni di affiliazione con il Governo di Singapore. I controlli modificano solo i valori locali; non sono previsti flussi di prenotazione o pagamento.

Leggi la specifica di supporto

Sistema di design Singapore Government I token del tema sono stratificati

Colori primitivi e uso semantico

Il file root definisce i grigi primitivi, il viola primario del prodotto e le altre famiglie di palette. I file dei temi chiaro e scuro associano poi questi valori primitivi a ruoli come testo predefinito, testo di supporto, superficie piena e bordo. In modalità scura, un ruolo di testo primario può cambiare anche se il ruolo della superficie piena primaria continua a usare lo stesso valore primitivo.

L’anteprima usa proprietà semantiche per lo sfondo del documento, il testo, il bordo e il pannello attenuato. Attivando sgds-night-theme sull’elemento root, si aggiornano quindi sia gli elementi personalizzati sia la composizione che li circonda. Un paragrafo con il nero impostato direttamente comprometterebbe questa relazione, anche se i controlli continuassero a cambiare correttamente.

La palette viola è il colore predefinito pubblicato del prodotto, non un motivo per impersonare un’agenzia governativa. L’identità di un’agenzia e l’uso autorizzato della testata richiedono un’autorizzazione specifica.

Leggi la specifica di supporto

Sistema di design Singapore Government Tipografia adattiva con valori effettivi

Leggi il token distribuito, non un rapporto abbreviato

Il file responsive.css attuale associa heading-xl a 32, 36 e 40 px nelle tre fasce, con altezze di riga rispettivamente di 40, 44 e 48 px. I cambiamenti avvengono a 1024 e 1440 px. Sono indipendenti dai punti di interruzione più piccoli della griglia, a 512 e 768 px. Body-md rimane a 16 px.

La panoramica pubblica sulla tipografia descrive i rapporti generali e i principi di abbinamento, mentre il foglio dei token distribuito contiene alias esatti in pixel per ogni ruolo. Questa guida usa tali alias, effettivamente disponibili, per indicare i valori da implementare. Mantieni la semantica delle intestazioni in HTML e applica un token visivo appropriato; il titolo di una piccola sezione non richiede un livello di intestazione artificialmente basso.

Il carattere previsto per il brand è Inter, con i pesi 300, 400, 600 e 700 documentati nella configurazione. L’esempio locale usa esplicitamente Arial al suo posto e non carica caratteri remoti. Nei servizi che lo adottano, carica e verifica il carattere scelto, senza affidarti soltanto al nome della famiglia CSS.

Leggi la specifica di supporto

Sistema di design Singapore Government Ruoli di spaziatura diversi

Non ridurre tutti gli spazi a un’unica scala

La scala primitiva degli spazi include 2 px, oltre a 4, 8, 12, 16 e valori maggiori. Gli alias per gli spazi fissi e per gli spazi di layout, dei componenti e del testo adattivi si basano su questi valori primitivi. Un layout-gap-md di base passa da 16 a 24 e poi a 32 px, mentre text-gap-md passa da 12 a 16 px e resta a 16 px. La parola «medio» non indica quindi lo stesso valore numerico in tutti i casi.

Il pianificatore usa una larghezza massima di 888 px per mantenere affiancate due aree di contenuto contenute: i controlli della quantità e il piano attuale. Sotto i 768 px, le dispone una sopra l’altra. È una scelta compositiva dell’applicazione, non l’affermazione che la griglia standard SGDS si fermi sempre a 888 px. Le regole più ampie per i contenitori standard sono elencate separatamente nel riferimento.

Leggi la specifica di supporto

Sistema di design Singapore Government Un controllo per conteggi con limiti

Usa la quantità per indicare un conteggio, non un identificativo

Un selettore di quantità è adatto a un conteggio ridotto che una persona può modificare di un’unità alla volta. L’esempio richiede da 1 a 5 partecipanti e da 0 a 3 kit condivisi. Sono limiti dimostrativi: un servizio reale deve ricavarli dalla disponibilità effettiva o dalle norme applicabili e indicarli nel testo di aiuto. Per codici postali, identificativi e importi esatti in valuta serve un altro tipo di campo.

Il componente nativo riunisce pulsanti icona per diminuire e aumentare attorno a un campo numerico. min, max e step sono valori numerici, value riflette il conteggio attuale, mentre label e hintText forniscono il contesto. Al raggiungimento di un limite, il pulsante corrispondente diventa non disponibile; anche l’inserimento diretto richiede comunque la convalida dei vincoli.

hasFeedback accetta la stringa style, text oppure entrambe. L’esempio usa entrambe e aggiunge uno specifico messaggio invalidFeedback. Trattare hasFeedback come un valore booleano copiato da un altro componente API farebbe perdere questa configurazione precisa.

<sgds-quantity-toggle
  id="people" name="people" label="Participants"
  hintText="Choose 1 to 5 participants"
  min="1" max="5" step="1" value="1"
  hasFeedback="both"
  invalidFeedback="Enter a whole number from 1 to 5">
</sgds-quantity-toggle>
<output id="participant-total">1</output>
<script>
  customElements.whenDefined('sgds-quantity-toggle').then(() => {
    const quantity = document.querySelector('#people');
    const update = () => {
      document.querySelector('#participant-total').textContent = String(quantity.value);
    };
    ['sgds-input', 'sgds-change'].forEach(name => {
      quantity.addEventListener(name, update);
    });
  });
</script>

Riferimento del codice

Leggi la specifica di supporto

Sistema di design Singapore Government Mantieni il riepilogo sincronizzato

Due percorsi di eventi e un’unica fonte di dati

Il riepilogo legge il valore di ciascun elemento host. Ascolta sia sgds-input sia sgds-change, perché le modifiche digitate e quelle confermate tramite i pulsanti non seguono necessariamente lo stesso percorso di eventi. Nel primo esempio locale, i test limitati all’inserimento da tastiera non rilevavano gli aggiornamenti dei pulsanti di incremento; l’esempio finale gestisce entrambi i casi.

Il pulsante Check plan richiama reportValidity su entrambi gli elementi nativi e mostra un messaggio di stato locale. Non trasforma un numero non valido in un totale plausibile. Reset assegna i valori iniziali agli elementi host e azzera lo stato di non validità visibile nell’applicazione con setInvalid(false), poi aggiorna il riepilogo dopo updateComplete.

Un campo disabilitato non equivale a un campo di sola lettura: il primo è escluso dall’invio del modulo, mentre il secondo conserva il proprio valore. Se un servizio reale blocca una quantità confermata durante la revisione, usa lo stato appropriato invece di disabilitare il campo solo per ottenere un aspetto grigio.

• Usa sgds-input e sgds-change quando un riepilogo deve gestire sia la digitazione sia i pulsanti di incremento.
• Leggi value dall’elemento host personalizzato, senza accedere al relativo shadow DOM.
• Mantieni distinti i messaggi locali di validità dall’esito positivo di una prenotazione o di un invio.

Leggi la specifica di supporto

Sistema di design Singapore Government Gli stili prima della registrazione

Carica la catena di dipendenze del tema

In un’applicazione con bundler, importa day.css, night.css e css/sgds.css in quest’ordine, poi importa una sola volta la libreria dei componenti. I file day e night importano root.css, che a sua volta importa responsive.css. Il file di base importa reboot.css e grid.css. Una copia statica deve mantenere queste dipendenze relative, non solo i primi tre file.

Il file ufficiale utility.css è un punto di ingresso per la configurazione Tailwind CSS v 4. Deve passare attraverso una build di Tailwind configurata: aggiungerlo come semplice foglio di stile del browser non genera tutte le classi di utilità sgds:. Questo esempio usa invece un layout CSS standard e proprietà personalizzate semantiche, quindi non presuppone alcuna build delle utilità.

Per l’esempio isolato nel browser, il file pubblicato è index.umd.min.js. I metadati del pacchetto menzionano ancora index.umd.js, ma il file non è presente nella distribuzione esaminata. L’anteprima locale usa il bundle minificato effettivamente disponibile; la configurazione npm usa l’importazione del pacchetto documentata per i bundler.

1. Fissa la versione 3.29.0 e importa i token del tema prima delle regole di base.
2. Fornisci Inter oppure scegli deliberatamente un carattere di riserva e testalo.
3. Registra gli elementi personalizzati una sola volta, attendi la loro definizione se necessario, poi aggiungi i listener dell’applicazione.

Leggi la specifica di supporto

Sistema di design Singapore Government Verifica insieme limiti e tema

I valori limite rivelano gli errori d’integrazione

Aumenta Participants due volte e verifica che sia il controllo sia il riepilogo mostrino 3. Digita direttamente 9 e seleziona Check plan: il componente dovrebbe mostrare il messaggio relativo all’intervallo e lo stato dovrebbe chiedere di correggere il valore. Modificalo in 5 e verifica che il controllo di incremento sia disabilitato mentre il valore rimane valido.

Dopo aver inserito le quantità, passa al tema scuro e verifica che i valori siano conservati, il riepilogo resti leggibile e i limiti continuino a funzionare correttamente. Seleziona Reset, poi ripeti il test con la tastiera: Tab dovrebbe raggiungere il campo e i pulsanti in un ordine sensato, mentre Invio o Spazio dovrebbero attivare il pulsante selezionato.

Il test locale verifica il comportamento dei componenti a 1440, 768 e 390 px e controlla che le dipendenze del tema siano servite localmente. Non garantisce il supporto dei browser né la certificazione di accessibilità per un futuro servizio governativo. Quel servizio dovrà testare l’intero flusso, i testi, la personalizzazione del tema e la gestione dei dati.

Leggi la specifica di supporto

Sistema di design Singapore Government Esempi di componenti del sistema di design

<sgds-quantity-toggle
  id="people" name="people" label="Participants"
  hintText="Choose 1 to 5 participants"
  min="1" max="5" step="1" value="1"
  hasFeedback="both"
  invalidFeedback="Enter a whole number from 1 to 5">
</sgds-quantity-toggle>
<output id="participant-total">1</output>
<script>
  customElements.whenDefined('sgds-quantity-toggle').then(() => {
    const quantity = document.querySelector('#people');
    const update = () => {
      document.querySelector('#participant-total').textContent = String(quantity.value);
    };
    ['sgds-input', 'sgds-change'].forEach(name => {
      quantity.addEventListener(name, update);
    });
  });
</script>

npm install --save-exact @govtechsg/[email protected]

/* globals.css — tokens before foundation rules */
@import "@govtechsg/sgds-web-component/themes/day.css";
@import "@govtechsg/sgds-web-component/themes/night.css";
@import "@govtechsg/sgds-web-component/css/sgds.css";
/* Only for a configured Tailwind CSS v4 build: */
/* @import "@govtechsg/sgds-web-component/css/utility.css"; */

// main.js — register custom elements once
import '@govtechsg/sgds-web-component';

// Enable the published night theme; omit class for day.
document.documentElement.classList.toggle('sgds-night-theme');

<!doctype html><html lang="en"><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>SGDS quantity specimen</title><link rel="stylesheet" href="vendor/sgds-3.29.0/themes/day.css"><link rel="stylesheet" href="vendor/sgds-3.29.0/themes/night.css"><link rel="stylesheet" href="vendor/sgds-3.29.0/css/sgds.css"><style>:root{--sgds-font-family-brand:Arial,sans-serif}*{box-sizing:border-box}body{margin:0;background:var(--sgds-bg-default);color:var(--sgds-color-default);font-family:var(--sgds-font-family-brand)}main{max-width:888px;margin:auto;padding:32px 20px}h1{font-size:var(--sgds-font-size-heading-xl);line-height:var(--sgds-line-height-xl);letter-spacing:var(--sgds-letter-spacing-tight)}h2{font-size:var(--sgds-font-size-heading-sm);line-height:var(--sgds-line-height-sm)}p{max-width:60ch;line-height:1.5}.eyebrow{color:var(--sgds-color-subtle);font-size:14px}.layout{display:grid;grid-template-columns:1fr 1fr;gap:var(--sgds-layout-gap-md);margin:32px 0}.control{border:1px solid var(--sgds-border-color-default);border-radius:var(--sgds-border-radius-md);padding:24px;background:var(--sgds-bg-alternate)}sgds-quantity-toggle{display:block;max-width:100%}dl{margin:24px 0}dt{color:var(--sgds-color-subtle)}dd{margin:0 0 16px;font-weight:600}.actions{display:flex;flex-wrap:wrap;gap:16px}#status{min-height:24px}button.native{font:inherit;background:transparent;border:1px solid var(--sgds-border-color-default);color:inherit;padding:8px 12px;border-radius:8px}button.native:focus-visible{outline:3px solid var(--sgds-primary-border-color-default);outline-offset:3px}@media(max-width:767px){.layout{grid-template-columns:1fr}.control{padding:20px}}</style><main><p class="eyebrow">Independent specimen · Community workshop planning</p><h1>Plan a small workshop group</h1><p>Adjust two bounded quantities and inspect the local summary. This example does not reserve places or equipment.</p><button class="native" id="theme" aria-pressed="false">Night theme</button><div class="layout"><section class="control"><h2>People and materials</h2><form id="planner"><sgds-quantity-toggle id="people" name="people" label="Participants" hintText="Choose 1 to 5 participants" min="1" max="5" step="1" value="1" hasFeedback="both" invalidFeedback="Enter a whole number from 1 to 5"></sgds-quantity-toggle><div style="height:24px"></div><sgds-quantity-toggle id="kits" name="kits" label="Shared material kits" hintText="Choose 0 to 3 kits" min="0" max="3" step="1" value="0" hasFeedback="both" invalidFeedback="Enter a whole number from 0 to 3"></sgds-quantity-toggle></form></section><section><h2>Current plan</h2><dl><dt>Participants</dt><dd id="p-value">1</dd><dt>Material kits</dt><dd id="k-value">0</dd></dl><p>These are demonstration limits. A real service should explain its own availability and eligibility rules.</p><div class="actions"><sgds-button id="review">Check plan</sgds-button><sgds-button id="reset" variant="outline">Reset</sgds-button></div><p id="status" role="status" aria-live="polite"></p></section></div></main><script src="vendor/sgds-3.29.0/index.umd.min.js"></script><script type="module">await Promise.all(['sgds-quantity-toggle','sgds-button'].map(x=>customElements.whenDefined(x)));const p=document.querySelector('#people'),k=document.querySelector('#kits'),status=document.querySelector('#status');await Promise.all([p.updateComplete,k.updateComplete]);const update=()=>{document.querySelector('#p-value').textContent=String(p.value);document.querySelector('#k-value').textContent=String(k.value);status.textContent=''};[p,k].forEach(x=>['sgds-input','sgds-change'].forEach(name=>x.addEventListener(name,update)));document.querySelector('#review').onclick=()=>{const validP=p.reportValidity(),validK=k.reportValidity();status.textContent=validP&&validK?'The quantities are within the demo limits. Nothing has been reserved.':'Correct the highlighted quantity before continuing.'};document.querySelector('#reset').onclick=async()=>{p.value=1;k.value=0;p.setInvalid(false);k.setInvalid(false);await Promise.all([p.updateComplete,k.updateComplete]);update()};document.querySelector('#theme').onclick=e=>{const night=document.documentElement.classList.toggle('sgds-night-theme');e.currentTarget.setAttribute('aria-pressed',String(night));e.currentTarget.textContent=night?'Day theme':'Night theme'};window.demoReady=true;</script></html>