@lifesg/react-design-system 4.0.0-alpha.13 → 4.0.0-alpha.14

package/skills/fds-build/resources/patterns/states.md

@@ -0,0 +1,300 @@
+# States Pattern
+
+Loading, empty, error, and success states for async operations and data absence.
+
+---
+
+## Loading states
+
+### Full-page loading
+
+```tsx
+import { Layout } from "@lifesg/react-design-system/layout";
+import { Card } from "@lifesg/react-design-system/card";
+import { Typography } from "@lifesg/react-design-system/typography";
+import { Spacing } from "@lifesg/react-design-system/theme";
+
+if (isLoading) {
+    return (
+        <Layout.Container type="grid">
+            <Layout.ColDiv xsCols={8} lgCols={12}>
+                <Card
+                    style={{
+                        textAlign: "center",
+                        padding: `${Spacing["spacing-64"]} ${Spacing["spacing-32"]}`,
+                    }}
+                >
+                    <LoadingSpinner />
+                    {/* import { LoadingSpinner } from "@lifesg/react-design-system/loading-spinner" */}
+                    <Typography.BodyBL>Loading...</Typography.BodyBL>
+                </Card>
+            </Layout.ColDiv>
+        </Layout.Container>
+    );
+}
+```
+
+### Skeleton loading (preferred for content-heavy pages)
+
+Render placeholder blocks matching the shape of real content. Use a CSS `pulse` animation (`opacity 0.5 → 1` at 1.5s). Show the same grid structure as the loaded state — same column count, same card shapes.
+
+### Button loading (inline async)
+
+```tsx
+<Button type="submit" loading={isSubmitting} disabled={isSubmitting}>
+    {isSubmitting ? "Submitting..." : "Submit"}
+</Button>
+```
+
+Always combine `loading` + `disabled` during async to prevent double-submission.
+
+---
+
+## Empty states
+
+### First-time use (no data)
+
+```tsx
+import { Card } from "@lifesg/react-design-system/card";
+import { Typography } from "@lifesg/react-design-system/typography";
+import { Button } from "@lifesg/react-design-system/button";
+import { Spacing } from "@lifesg/react-design-system/theme";
+
+<Card
+    style={{
+        textAlign: "center",
+        padding: `${Spacing["spacing-64"]} ${Spacing["spacing-32"]}`,
+    }}
+>
+    <Typography.HeadingSM>No items yet</Typography.HeadingSM>
+    <Typography.BodyBL>
+        Get started by creating your first item
+    </Typography.BodyBL>
+    <Button
+        icon={<PlusIcon />}
+        style={{ marginTop: Spacing["spacing-24"] }}
+        onClick={handleCreate}
+    >
+        Create item
+    </Button>
+</Card>;
+```
+
+### No search results
+
+```tsx
+<Card
+    style={{
+        textAlign: "center",
+        padding: `${Spacing["spacing-64"]} ${Spacing["spacing-32"]}`,
+    }}
+>
+    <Typography.HeadingSM>No results found</Typography.HeadingSM>
+    <Typography.BodyBL>Try adjusting your search or filters</Typography.BodyBL>
+    <Button
+        styleType="secondary"
+        style={{ marginTop: Spacing["spacing-24"] }}
+        onClick={handleClearFilters}
+    >
+        Clear filters
+    </Button>
+</Card>
+```
+
+For listing pages, prefer `ErrorDisplay type="no-item-found"` over a custom card.
+
+### Empty section (within a page)
+
+```tsx
+import { Typography } from "@lifesg/react-design-system/typography";
+import { Colour, Spacing } from "@lifesg/react-design-system/theme";
+
+<div style={{ textAlign: "center", padding: `${Spacing["spacing-32"]} 0` }}>
+    <Typography.BodySM style={{ color: Colour["text-subtler"] }}>
+        No recent activity to display
+    </Typography.BodySM>
+</div>;
+```
+
+---
+
+## Error states
+
+### API / fetch error
+
+```tsx
+import { Alert } from "@lifesg/react-design-system/alert";
+import { Layout } from "@lifesg/react-design-system/layout";
+
+if (error) {
+    return (
+        <Layout.Container type="grid">
+            <Layout.ColDiv xsCols={8} lgCols={12}>
+                <Alert
+                    type="error"
+                    actionLink={{
+                        children: "Try again",
+                        onClick: () => window.location.reload(),
+                    }}
+                >
+                    {error.message}
+                </Alert>
+            </Layout.ColDiv>
+        </Layout.Container>
+    );
+}
+```
+
+### 404 Not found
+
+```tsx
+import { Card } from "@lifesg/react-design-system/card";
+import { Typography } from "@lifesg/react-design-system/typography";
+import { Button } from "@lifesg/react-design-system/button";
+import { Spacing } from "@lifesg/react-design-system/theme";
+
+<Card
+    style={{
+        textAlign: "center",
+        padding: `${Spacing["spacing-64"]} ${Spacing["spacing-32"]}`,
+    }}
+>
+    <Typography.HeadingXL>404</Typography.HeadingXL>
+    <Typography.HeadingSM>Page not found</Typography.HeadingSM>
+    <Typography.BodyBL>
+        The page you're looking for doesn't exist or has been moved
+    </Typography.BodyBL>
+    <Button
+        style={{ marginTop: Spacing["spacing-24"] }}
+        onClick={() => navigate("/")}
+    >
+        Go to home
+    </Button>
+</Card>;
+```
+
+### Permission denied
+
+```tsx
+<Card
+    style={{
+        textAlign: "center",
+        padding: `${Spacing["spacing-64"]} ${Spacing["spacing-32"]}`,
+    }}
+>
+    <Typography.HeadingSM>Access denied</Typography.HeadingSM>
+    <Typography.BodyBL>
+        You don't have permission to view this page
+    </Typography.BodyBL>
+    <Button
+        styleType="secondary"
+        style={{ marginTop: Spacing["spacing-24"] }}
+        onClick={() => navigate("/")}
+    >
+        Go to home
+    </Button>
+</Card>
+```
+
+---
+
+## Success states
+
+### Inline success
+
+```tsx
+<Alert
+    type="success"
+    actionLink={{ children: "View details", onClick: handleViewDetails }}
+>
+    {successMessage}
+</Alert>
+```
+
+### Toast notification
+
+```tsx
+import { Toast } from "@lifesg/react-design-system/toast";
+
+<Toast type="success">Changes saved successfully</Toast>
+<Toast type="error">Failed to save changes</Toast>
+```
+
+Use `Toast` for non-critical feedback. Use `Alert` for errors requiring action.
+
+### Full-page success (major operations)
+
+```tsx
+import { Card } from "@lifesg/react-design-system/card";
+import { Typography } from "@lifesg/react-design-system/typography";
+import { Button } from "@lifesg/react-design-system/button";
+import { Spacing } from "@lifesg/react-design-system/theme";
+
+<Card
+    style={{
+        textAlign: "center",
+        padding: `${Spacing["spacing-64"]} ${Spacing["spacing-32"]}`,
+    }}
+>
+    <Typography.HeadingMD>
+        Application submitted successfully
+    </Typography.HeadingMD>
+    <Typography.BodyBL>Your application is being processed</Typography.BodyBL>
+    <div
+        style={{
+            display: "flex",
+            gap: Spacing["spacing-16"],
+            justifyContent: "center",
+            marginTop: Spacing["spacing-32"],
+        }}
+    >
+        <Button onClick={() => navigate("/applications")}>
+            View applications
+        </Button>
+        <Button styleType="secondary" onClick={() => navigate("/")}>
+            Go to home
+        </Button>
+    </div>
+</Card>;
+```
+
+---
+
+## State management pattern
+
+```tsx
+const [state, setState] = useState({
+    data: null,
+    isLoading: true,
+    error: null,
+});
+
+// In component:
+if (state.isLoading) return <LoadingState />;
+if (state.error) return <ErrorState message={state.error} />;
+if (!state.data || state.data.length === 0) return <EmptyState />;
+return <DataDisplay data={state.data} />;
+```
+
+---
+
+## Rules
+
+-   Show loading feedback for any operation taking longer than 200ms
+-   Prefer skeleton loading over a spinner for content-heavy initial page loads
+-   Always provide a way out of an error state (retry, go home)
+-   Empty state messages: 1–2 sentences max, action-oriented, sentence case
+-   Error messages: name the specific problem — never "An error occurred"
+-   `Toast` auto-dismisses — use for confirmations; use `Alert` for errors needing action
+-   Full-page state containers: `padding: spacing-64 spacing-32`, `textAlign: center`, inside a `Card`
+-   Disable interactive elements during loading to prevent race conditions
+-   Use `style={{}}` with `Spacing` and `Colour` tokens for all custom spacing and colour
+
+## Anti-patterns
+
+-   Do not show a spinner for operations under 200ms — causes flicker
+-   Do not show an empty container with no state message in a listing page
+-   Do not use `Toast` for critical errors — user may miss it
+-   Do not use generic error text — always tell the user what failed
+-   Do not leave submit buttons enabled during async — always set `disabled` + `loading`
+-   Do not hardcode `px` values or hex colours — always use `Spacing` and `Colour` tokens

package/skills/fds-build/resources/setup/setup.md

@@ -0,0 +1,202 @@
+# App Setup — Flagship v4
+
+Full project setup for `@lifesg/react-design-system` v4. Work through all steps before writing any component code.
+
+---
+
+## Step 1 — Install packages
+
+```bash
+npm install @lifesg/react-design-system @lifesg/react-icons @floating-ui/react
+```
+
+Do NOT install `styled-components` — it is not used in v4.
+
+---
+
+## Step 2 — CDN stylesheets
+
+Add these stylesheets to normalise browser styles and display fonts.
+
+```html
+<link
+    rel="stylesheet"
+    type="text/css"
+    href="https://assets.life.gov.sg/react-design-system/v4/css/main.css"
+/>
+<link
+    rel="stylesheet"
+    type="text/css"
+    href="https://assets.life.gov.sg/react-design-system/v3/css/open-sans.css"
+/>
+```
+
+Or if you are importing to an existing CSS file:
+
+```css
+@import url("https://assets.life.gov.sg/react-design-system/v4/css/main.css");
+@import url("https://assets.life.gov.sg/react-design-system/v3/css/open-sans.css");
+```
+
+Replace `open-sans` with the font for your theme:
+
+| Theme                                    | Font CSS                           |
+| ---------------------------------------- | ---------------------------------- |
+| lifesg, ccube, mylegacy, oneservice, rbs | `open-sans`                        |
+| bookingsg, careercompass, smgs           | `plus-jakarta-sans`                |
+| spf, vica, websg, wise, wogaa            | `public-sans`                      |
+| sgw-digital-lobby, supportgowhere        | `libre-franklin`                   |
+| pa                                       | `lato`                             |
+| imda                                     | `montserrat`                       |
+| tote-board                               | `inter`                            |
+| a11y-playground                          | `atkinson-hyperlegible-next`       |
+| sportsg-orange                           | `apfel-grotezk` + `hanken-grotesk` |
+
+---
+
+## Step 3 — Theme stylesheet
+
+In your application's CSS entrypoint, import the theme stylesheet:
+
+```css
+@import "@lifesg/react-design-system/theme/styles/lifesg.css";
+```
+
+> CSS `@import` from `node_modules` requires your framework or build tool to support it. Vite and Next.js resolve this automatically; other build tools may need a CSS resolver configured.
+
+Or in your application's JavaScript entrypoint, import the theme stylesheet:
+
+```tsx
+import "@lifesg/react-design-system/theme/styles/lifesg.css";
+```
+
+Replace `lifesg` with your chosen theme slug: `a11y-playground` · `bookingsg` · `careercompass` · `ccube` · `imda` · `lifesg` · `mylegacy` · `oneservice` · `pa` · `rbs` · `sgw-digital-lobby` · `smgs` · `spf` · `sportsg-orange` · `supportgowhere` · `tote-board` · `vica` · `websg` · `wise` · `wogaa`
+
+---
+
+## Step 4 — ThemeProvider
+
+Wrap your app root in `ThemeProvider`. The `theme` prop is a string matching the slug used in Step 3.
+
+```tsx
+import { ThemeProvider } from "@lifesg/react-design-system/theme";
+
+const App = () => {
+    return (
+        <ThemeProvider theme="lifesg">
+            <Component />
+        </ThemeProvider>
+    );
+};
+```
+
+**Dark/light mode:** `mode` prop defaults to `"auto"` (OS preference).
+
+```tsx
+<ThemeProvider theme="lifesg" mode="light">  {/* force light */}
+<ThemeProvider theme="lifesg" mode="dark">   {/* force dark */}
+```
+
+---
+
+## Vite
+
+No special configuration needed for the design system. Standard React setup:
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+
+export default defineConfig({
+    plugins: [react()],
+});
+```
+
+---
+
+## Next.js App Router
+
+No special `next.config.js` is needed. Suggested configuration below.
+
+### CSS
+
+Create a global CSS file with all three imports — CDN stylesheets and theme:
+
+```css
+/* global.css */
+@import url("https://assets.life.gov.sg/react-design-system/v4/css/main.css");
+@import url("https://assets.life.gov.sg/react-design-system/v3/css/open-sans.css");
+@import "@lifesg/react-design-system/theme/styles/lifesg.css";
+```
+
+Wrap the app in a flex column layout so the footer stays pinned to the bottom on short pages:
+
+```css
+body {
+    min-height: 100vh;
+    display: flex;
+    flex-direction: column;
+}
+
+main {
+    flex: 1;
+}
+
+.theme-provider {
+    display: flex;
+    flex-direction: column;
+}
+```
+
+### ThemeProvider
+
+`ThemeProvider` is a client component, so create a wrapper:
+
+```tsx
+// src/app/providers.tsx
+"use client";
+import { ThemeProvider } from "@lifesg/react-design-system/theme";
+
+export default function Providers({ children }: { children: React.ReactNode }) {
+    return (
+        <ThemeProvider theme="lifesg" className="theme-provider">
+            {children}
+        </ThemeProvider>
+    );
+}
+```
+
+### Root layout
+
+Import the global CSS and the providers wrapper in `layout.tsx`:
+
+```tsx
+// src/app/layout.tsx
+import "./global.css";
+import Providers from "./providers";
+
+export default function RootLayout({
+    children,
+}: {
+    children: React.ReactNode;
+}) {
+    return (
+        <html lang="en">
+            <body>
+                <Providers>{children}</Providers>
+            </body>
+        </html>
+    );
+}
+```
+
+---
+
+## Verification checklist
+
+-   [ ] `@lifesg/react-design-system`, `@lifesg/react-icons`, `@floating-ui/react` installed
+-   [ ] `styled-components` NOT installed
+-   [ ] `main.css` and font CDN links imported in HTML doc or CSS file
+-   [ ] `@lifesg/react-design-system/theme/styles/{theme}.css` imported in entrypoint or CSS file
+-   [ ] `ThemeProvider` wraps app root with correct theme string