peer-ai-standards 1.0.0-next.0

package/dist/core/design-accessibility.d.ts

@@ -0,0 +1,124 @@
+export declare const designAccessibility: ({
+    id: string;
+    domain: "design-accessibility";
+    title: string;
+    rule: string;
+    why: string;
+    ask: string;
+    stage: "mvp";
+    check: "auto";
+    severity: "medium";
+    sources?: never;
+} | {
+    id: string;
+    domain: "design-accessibility";
+    title: string;
+    rule: string;
+    why: string;
+    ask: string;
+    stage: "mvp";
+    check: "ai-review";
+    severity: "low";
+    sources?: never;
+} | {
+    id: string;
+    domain: "design-accessibility";
+    title: string;
+    rule: string;
+    why: string;
+    ask: string;
+    stage: "mvp";
+    check: "ai-review";
+    severity: "medium";
+    sources?: never;
+} | {
+    id: string;
+    domain: "design-accessibility";
+    title: string;
+    rule: string;
+    why: string;
+    ask: string;
+    stage: "mvp";
+    check: "ai-review";
+    severity: "medium";
+    sources: {
+        name: string;
+        ref: string;
+        url: string;
+    }[];
+} | {
+    id: string;
+    domain: "design-accessibility";
+    title: string;
+    rule: string;
+    why: string;
+    ask: string;
+    stage: "prototype";
+    check: "auto";
+    severity: "medium";
+    sources: {
+        name: string;
+        ref: string;
+        url: string;
+    }[];
+} | {
+    id: string;
+    domain: "design-accessibility";
+    title: string;
+    rule: string;
+    why: string;
+    ask: string;
+    stage: "prototype";
+    check: "ai-review";
+    severity: "medium";
+    sources: {
+        name: string;
+        ref: string;
+        url: string;
+    }[];
+} | {
+    id: string;
+    domain: "design-accessibility";
+    title: string;
+    rule: string;
+    why: string;
+    ask: string;
+    stage: "mvp";
+    check: "ai-review";
+    severity: "high";
+    sources: {
+        name: string;
+        ref: string;
+        url: string;
+    }[];
+} | {
+    id: string;
+    domain: "design-accessibility";
+    title: string;
+    rule: string;
+    why: string;
+    ask: string;
+    stage: "mvp";
+    check: "auto";
+    severity: "medium";
+    sources: {
+        name: string;
+        ref: string;
+        url: string;
+    }[];
+} | {
+    id: string;
+    domain: "design-accessibility";
+    title: string;
+    rule: string;
+    why: string;
+    ask: string;
+    stage: "mvp";
+    check: "auto";
+    severity: "low";
+    sources: {
+        name: string;
+        ref: string;
+        url: string;
+    }[];
+})[];

package/dist/core/design-accessibility.js

@@ -0,0 +1,199 @@
+// Design tokens, shared components, and making the product work for everyone. Accessibility
+// rules cite the WCAG 2.2 success criterion they come from, checked against the W3C's text. The
+// numbers a platform sets, such as touch target sizes, are in the stack profiles.
+const WCAG = "WCAG 2.2";
+const sc = (anchor) => `https://www.w3.org/TR/WCAG22/#${anchor}`;
+export const designAccessibility = [
+    {
+        id: "DES-01",
+        domain: "design-accessibility",
+        title: "Design values come from tokens",
+        rule: "Colours, spacing, corner radii and font sizes come from design tokens. None is written directly into a screen or component.",
+        why: "A hard-coded value is missed by every rebrand, dark theme and accessibility fix that changes the tokens.",
+        ask: "Does this change write a colour, spacing, radius or font size directly?",
+        stage: "mvp",
+        check: "auto",
+        severity: "medium",
+    },
+    {
+        id: "DES-02",
+        domain: "design-accessibility",
+        title: "Tokens come from one place, used by every app",
+        rule: "Design tokens have one source, independent of any framework, and every app reads from it: light and dark palettes, type scale, spacing, radii and elevation.",
+        why: "Two copies of the tokens drift, and the web and mobile apps stop looking like one product.",
+        ask: "Does this change define design values anywhere other than the one token source?",
+        stage: "mvp",
+        check: "auto",
+        severity: "medium",
+    },
+    {
+        id: "DES-03",
+        domain: "design-accessibility",
+        title: "Token names say what they're for",
+        rule: "Tokens are named for their purpose, such as `surface`, `accent` or `danger`, never for how they look, such as `blue500`.",
+        why: "Names that describe purpose survive a rebrand and a dark theme. Names that describe a colour are wrong the day the colour changes.",
+        ask: "Does any token in this change describe how it looks rather than what it's for?",
+        stage: "mvp",
+        check: "ai-review",
+        severity: "low",
+    },
+    {
+        id: "DES-04",
+        domain: "design-accessibility",
+        title: "Screens are built from the shared components",
+        rule: "Screens are built only from the shared set of interface components. A screen that needs a new one adds it to the set, rather than building it inline.",
+        why: "Inline one-offs are where inconsistency, missing states and accessibility gaps collect.",
+        ask: "Does any screen in this change build an interface element instead of using a shared component?",
+        stage: "mvp",
+        check: "auto",
+        severity: "medium",
+    },
+    {
+        id: "DES-05",
+        domain: "design-accessibility",
+        title: "Every shared component comes with all its states",
+        rule: "Every shared component has all its states: default, pressed, focused, disabled, loading, error and, where it applies, empty. One without them isn't finished.",
+        why: "A missing state is found by a person at the worst moment: a button that looks tappable while it's still saving.",
+        ask: "Does every shared component in this change have all its states?",
+        stage: "mvp",
+        check: "ai-review",
+        severity: "medium",
+    },
+    {
+        id: "DES-06",
+        domain: "design-accessibility",
+        title: "The danger colour means one thing",
+        rule: "The danger colour is kept for the one meaning the project gives it, such as money going wrong or a safety warning. It's never decoration, and never a general error.",
+        why: "A signal used for everything teaches people to ignore it, including the time it matters.",
+        ask: "Is the danger colour in this change used for anything but its one meaning?",
+        stage: "mvp",
+        check: "ai-review",
+        severity: "medium",
+    },
+    {
+        id: "DES-07",
+        domain: "design-accessibility",
+        title: "Information is never shown by colour alone",
+        rule: "Anything shown with colour, such as a status or an error, is also shown with text, a shape or an icon with a label.",
+        why: "About one man in twelve has some colour blindness, and screen readers don't read colours at all.",
+        ask: "Is any information in this change shown by colour alone?",
+        stage: "mvp",
+        check: "ai-review",
+        severity: "medium",
+        sources: [{ name: WCAG, ref: "1.4.1, level A", url: sc("use-of-color") }],
+    },
+    {
+        id: "DES-08",
+        domain: "design-accessibility",
+        title: "Every control has an accessible name",
+        rule: "Every button, link and control has a name a screen reader can announce, including buttons that show only an icon.",
+        why: 'An unlabelled control is announced as "button", and the person has no way to know what it does.',
+        ask: "Does every control in this change have an accessible name?",
+        stage: "prototype",
+        check: "auto",
+        severity: "medium",
+        sources: [{ name: WCAG, ref: "4.1.2, level A", url: sc("name-role-value") }],
+    },
+    {
+        id: "DES-09",
+        domain: "design-accessibility",
+        title: "Form fields have labels",
+        rule: "Every form field has a visible label that stays visible while the person types. A placeholder isn't a label.",
+        why: "A placeholder disappears as soon as someone types, and many screen readers don't announce it.",
+        ask: "Does every form field in this change have a label, not just a placeholder?",
+        stage: "prototype",
+        check: "ai-review",
+        severity: "medium",
+        sources: [
+            { name: WCAG, ref: "3.3.2, level A", url: sc("labels-or-instructions") },
+            { name: WCAG, ref: "1.3.1, level A", url: sc("info-and-relationships") },
+        ],
+    },
+    {
+        id: "DES-10",
+        domain: "design-accessibility",
+        title: "Everything works with a keyboard",
+        rule: "On the web, everything a person can do with a mouse or a tap, they can do with a keyboard alone.",
+        why: "Many people can't use a mouse, and a control a keyboard can't reach locks them out of the whole task.",
+        ask: "Can everything in this change be done with a keyboard alone?",
+        stage: "mvp",
+        check: "ai-review",
+        severity: "high",
+        sources: [{ name: WCAG, ref: "2.1.1, level A", url: sc("keyboard") }],
+    },
+    {
+        id: "DES-11",
+        domain: "design-accessibility",
+        title: "Focus is always visible",
+        rule: "The element that has keyboard focus is always clearly visible.",
+        why: "Someone using a keyboard can't act on what they can't see is selected.",
+        ask: "Is keyboard focus visible on everything in this change?",
+        stage: "mvp",
+        check: "auto",
+        severity: "medium",
+        sources: [{ name: WCAG, ref: "2.4.7, level AA", url: sc("focus-visible") }],
+    },
+    {
+        id: "DES-12",
+        domain: "design-accessibility",
+        title: "Dragging always has an alternative",
+        rule: "Anything done by dragging can also be done without dragging, such as with buttons to move an item up or down.",
+        why: "Dragging needs a steady hand and a pointer, which many people don't have.",
+        ask: "Can everything this change does by dragging also be done another way?",
+        stage: "mvp",
+        check: "ai-review",
+        severity: "medium",
+        sources: [{ name: WCAG, ref: "2.5.7, level AA", url: sc("dragging-movements") }],
+    },
+    {
+        id: "DES-13",
+        domain: "design-accessibility",
+        title: "Contrast meets WCAG AA in every theme",
+        rule: "Text, icons and control borders have enough contrast against their background in every theme: at least 4.5 to 1 for normal text.",
+        why: "Low contrast is unreadable in sunlight, on cheap screens, and for many people with low vision.",
+        ask: "Does every colour pair in this change meet WCAG AA contrast, in every theme?",
+        stage: "mvp",
+        check: "auto",
+        severity: "medium",
+        sources: [
+            { name: WCAG, ref: "1.4.3, level AA", url: sc("contrast-minimum") },
+            { name: WCAG, ref: "1.4.11, level AA", url: sc("non-text-contrast") },
+        ],
+    },
+    {
+        id: "DES-14",
+        domain: "design-accessibility",
+        title: "Text follows the person's text size",
+        rule: "Text grows with the person's text size setting, and the layout still works when it does.",
+        why: "People who need larger text set it once, and an app that ignores it is one they can't read.",
+        ask: "Does all text in this change follow the person's text size setting?",
+        stage: "mvp",
+        check: "ai-review",
+        severity: "medium",
+        sources: [{ name: WCAG, ref: "1.4.4, level AA", url: sc("resize-text") }],
+    },
+    {
+        id: "DES-15",
+        domain: "design-accessibility",
+        title: "Touch targets are large enough",
+        rule: "Everything a person taps or clicks is large enough to hit reliably. Each platform's profile sets the size.",
+        why: "Small targets cause mis-taps for everyone, and for people with tremors they make an app unusable.",
+        ask: "Is every tap or click target in this change at least its platform's minimum size?",
+        stage: "mvp",
+        check: "auto",
+        severity: "medium",
+        sources: [{ name: WCAG, ref: "2.5.8, level AA", url: sc("target-size-minimum") }],
+    },
+    {
+        id: "DES-16",
+        domain: "design-accessibility",
+        title: "Animation respects the reduced-motion setting",
+        rule: "Every animation that isn't essential stops or softens when the person has asked for reduced motion.",
+        why: "Movement on screen can cause dizziness and nausea for people with vestibular disorders.",
+        ask: "Does every animation in this change respect the reduced-motion setting?",
+        stage: "mvp",
+        check: "auto",
+        severity: "low",
+        sources: [{ name: WCAG, ref: "2.3.3, level AAA", url: sc("animation-from-interactions") }],
+    },
+];

package/dist/core/frontend.d.ts

@@ -0,0 +1,77 @@
+export declare const frontend: ({
+    id: string;
+    domain: "frontend";
+    title: string;
+    rule: string;
+    why: string;
+    ask: string;
+    stage: "mvp";
+    check: "ai-review";
+    severity: "medium";
+    sources?: never;
+    when?: never;
+} | {
+    id: string;
+    domain: "frontend";
+    title: string;
+    rule: string;
+    why: string;
+    ask: string;
+    stage: "prototype";
+    check: "ai-review";
+    severity: "medium";
+    sources?: never;
+    when?: never;
+} | {
+    id: string;
+    domain: "frontend";
+    title: string;
+    rule: string;
+    why: string;
+    ask: string;
+    stage: "mvp";
+    check: "ai-review";
+    severity: "low";
+    sources?: never;
+    when?: never;
+} | {
+    id: string;
+    domain: "frontend";
+    title: string;
+    rule: string;
+    why: string;
+    ask: string;
+    stage: "mvp";
+    check: "auto";
+    severity: "low";
+    sources?: never;
+    when?: never;
+} | {
+    id: string;
+    domain: "frontend";
+    title: string;
+    rule: string;
+    why: string;
+    ask: string;
+    stage: "mvp";
+    check: "ai-review";
+    severity: "medium";
+    sources: {
+        name: string;
+        ref: string;
+        url: string;
+    }[];
+    when?: never;
+} | {
+    id: string;
+    domain: "frontend";
+    title: string;
+    rule: string;
+    why: string;
+    ask: string;
+    stage: "mvp";
+    check: "ai-review";
+    severity: "high";
+    when: "offline"[];
+    sources?: never;
+})[];

package/dist/core/frontend.js

@@ -0,0 +1,109 @@
+// How screens get, hold and show data, whatever the framework. Each stack profile says how.
+const WCAG = "WCAG 2.2";
+const sc = (anchor) => `https://www.w3.org/TR/WCAG22/#${anchor}`;
+export const frontend = [
+    {
+        id: "FE-01",
+        domain: "frontend",
+        title: "Data from the server lives in one cache, not in screen state",
+        rule: "Data that came from a server or a stored source is read from one shared cache, never copied into a screen's own state.",
+        why: "A copy goes stale, sends duplicate requests, and races with the original when someone moves quickly between screens.",
+        ask: "Does this change copy server data into a screen's own state?",
+        stage: "mvp",
+        check: "ai-review",
+        severity: "medium",
+    },
+    {
+        id: "FE-02",
+        domain: "frontend",
+        title: "Values that follow from other data are calculated, never stored",
+        rule: "Totals, counts and statuses that follow from other data are calculated when they're read, never stored alongside it.",
+        why: "A stored copy of a calculated value is how two screens come to disagree.",
+        ask: "Does this change store a value that could be calculated from other data?",
+        stage: "prototype",
+        check: "ai-review",
+        severity: "medium",
+    },
+    {
+        id: "FE-03",
+        domain: "frontend",
+        title: "Truly global state lives in one store; everything else stays local",
+        rule: "State that the whole app shares lives in one store. Everything else stays in the component or feature that uses it.",
+        why: "Global state is shared by everything, so every piece of it is a way for one part of the app to break another.",
+        ask: "Is any state in this change made global when only one part of the app uses it?",
+        stage: "mvp",
+        check: "ai-review",
+        severity: "low",
+    },
+    {
+        id: "FE-04",
+        domain: "frontend",
+        title: "Values aren't passed down through layers that don't use them",
+        rule: "A value is passed through only a few components that don't use it; the profile sets how many. Past that, it's fixed with composition first, then shared context, then a store.",
+        why: '"No prop drilling" can\'t be enforced because nobody agrees where it starts. A number can be counted in review.',
+        ask: "Does any value in this change pass through more components that don't use it than the profile allows?",
+        stage: "mvp",
+        check: "ai-review",
+        severity: "low",
+    },
+    {
+        id: "FE-05",
+        domain: "frontend",
+        title: "A component fetches data or shows it, not both",
+        rule: "Data is fetched where a screen begins. Everything below it receives what it needs and only shows it.",
+        why: "A component that only shows what it's given can be tested and reused without a network.",
+        ask: "Does any component in this change both fetch data and show it?",
+        stage: "mvp",
+        check: "ai-review",
+        severity: "medium",
+    },
+    {
+        id: "FE-06",
+        domain: "frontend",
+        title: "Only screens know about navigation",
+        rule: "Only a screen knows how to move to another screen. Components below it receive what to do as a function.",
+        why: "A component that navigates on its own can't be reused anywhere the route is different.",
+        ask: "Does any component in this change, other than a screen, navigate?",
+        stage: "mvp",
+        check: "auto",
+        severity: "low",
+    },
+    {
+        id: "FE-07",
+        domain: "frontend",
+        title: "Every screen that waits handles loading, empty and error",
+        rule: "Every screen or component that waits for data shows loading, empty and error states explicitly. An endless spinner is a bug.",
+        why: "The happy path is the only one that gets built by default, and people meet the others first on a bad connection.",
+        ask: "Does everything in this change that waits for data handle loading, empty and error?",
+        stage: "mvp",
+        check: "ai-review",
+        severity: "medium",
+    },
+    {
+        id: "FE-08",
+        domain: "frontend",
+        title: "An error message says what happened and what to do next",
+        rule: 'An error message tells the person what went wrong and what they can do about it. A bare "Something went wrong" isn\'t enough.',
+        why: "A message that explains nothing leaves the person stuck, and turns into a support request.",
+        ask: "Does every error message in this change say what happened and what to do next?",
+        stage: "mvp",
+        check: "ai-review",
+        severity: "medium",
+        sources: [
+            { name: WCAG, ref: "3.3.1, level A", url: sc("error-identification") },
+            { name: WCAG, ref: "3.3.3, level AA", url: sc("error-suggestion") },
+        ],
+    },
+    {
+        id: "FE-09",
+        domain: "frontend",
+        title: "Offline is a state, not an error",
+        rule: "With no connection, the app says so, keeps what the person did, and catches up when it's back online. Nothing typed is lost.",
+        why: "People lose connection in lifts, on trains and in basements, and losing their work there teaches them not to trust the app.",
+        ask: "Does this change keep working, and keep what the person did, with no connection?",
+        stage: "mvp",
+        check: "ai-review",
+        severity: "high",
+        when: ["offline"],
+    },
+];

package/dist/core/mobile.d.ts

@@ -0,0 +1,46 @@
+export declare const mobile: ({
+    id: string;
+    domain: "mobile";
+    title: string;
+    rule: string;
+    why: string;
+    ask: string;
+    stage: "mvp";
+    check: "ai-review";
+    severity: "high";
+    sources: {
+        name: string;
+        ref: string;
+        url: string;
+    }[];
+} | {
+    id: string;
+    domain: "mobile";
+    title: string;
+    rule: string;
+    why: string;
+    ask: string;
+    stage: "mvp";
+    check: "ai-review";
+    severity: "medium";
+    sources: {
+        name: string;
+        ref: string;
+        url: string;
+    }[];
+} | {
+    id: string;
+    domain: "mobile";
+    title: string;
+    rule: string;
+    why: string;
+    ask: string;
+    stage: "production";
+    check: "ai-review";
+    severity: "medium";
+    sources: {
+        name: string;
+        ref: string;
+        url: string;
+    }[];
+})[];

package/dist/core/mobile.js

@@ -0,0 +1,83 @@
+// What phone apps need beyond the frontend rules. Security rules cite the OWASP Mobile
+// Application Security Verification Standard (MASVS) 2.1.0 control they come from, checked
+// against OWASP's own repository. Platform numbers, such as touch target sizes, are in the
+// stack profiles.
+const MASVS = "OWASP MASVS 2.1.0";
+const control = (id) => `https://github.com/OWASP/masvs/blob/master/controls/${id}.md`;
+export const mobile = [
+    {
+        id: "MOB-01",
+        domain: "mobile",
+        title: "Sensitive data on the phone is kept in secure storage",
+        rule: "Session tokens, keys and other sensitive data on the phone are kept in the platform's secure storage, such as the iOS Keychain or the Android Keystore, never in ordinary app storage.",
+        why: "Ordinary app storage can be read from a backup, a rooted phone or another app's exploit. Secure storage is encrypted and tied to the device.",
+        ask: "Does this change keep any token, key or sensitive data in ordinary storage on the phone?",
+        stage: "mvp",
+        check: "ai-review",
+        severity: "high",
+        sources: [{ name: MASVS, ref: "MASVS-STORAGE-1", url: control("MASVS-STORAGE-1") }],
+    },
+    {
+        id: "MOB-02",
+        domain: "mobile",
+        title: "Sensitive data doesn't leak from the phone",
+        rule: "Sensitive data doesn't leak through the device's logs, backups, clipboard, keyboard suggestions or the screenshot shown in the app switcher.",
+        why: "Each of these is read by something other than your app, and some of them are copied off the phone.",
+        ask: "Could sensitive data in this change leak through logs, backups, the clipboard, the keyboard or the app switcher?",
+        stage: "mvp",
+        check: "ai-review",
+        severity: "medium",
+        sources: [{ name: MASVS, ref: "MASVS-STORAGE-2", url: control("MASVS-STORAGE-2") }],
+    },
+    {
+        id: "MOB-03",
+        domain: "mobile",
+        title: "An in-app browser opens only pages you trust",
+        rule: "An in-app browser (a WebView) loads only the app's own pages or ones on an allow-list. JavaScript and bridges to the app's code are switched on only where needed, and a link from outside, such as a QR code or a deep link, is checked before it's opened.",
+        why: "A WebView that opens any page runs an attacker's page inside your app, with whatever access the app gives it.",
+        ask: "Can any in-app browser in this change open a page that isn't trusted?",
+        stage: "mvp",
+        check: "ai-review",
+        severity: "high",
+        sources: [{ name: MASVS, ref: "MASVS-PLATFORM-2", url: control("MASVS-PLATFORM-2") }],
+    },
+    {
+        id: "MOB-04",
+        domain: "mobile",
+        title: "Links into the app are untrusted input",
+        rule: "Anything that arrives from outside the app, through a deep link, a notification or another app, is validated like any other untrusted input before it's used.",
+        why: "Anyone can craft a link that opens your app, so a deep link is a door anyone can knock on.",
+        ask: "Is everything that reaches this change through a link, notification or another app validated?",
+        stage: "mvp",
+        check: "ai-review",
+        severity: "medium",
+        sources: [{ name: MASVS, ref: "MASVS-CODE-4", url: control("MASVS-CODE-4") }],
+    },
+    {
+        id: "MOB-05",
+        domain: "mobile",
+        title: "Permissions are asked for when needed, at the least level",
+        rule: "The app asks for each permission when the feature that needs it is used, says why, and asks for the least it can, such as location while the app is in use rather than all the time.",
+        why: "A permission asked for up front, or at a higher level than needed, is refused by careful people, rejected by app stores, and a privacy risk when granted.",
+        ask: "Does this change ask for a permission earlier, or at a higher level, than the feature needs?",
+        stage: "mvp",
+        check: "ai-review",
+        severity: "high",
+        sources: [
+            { name: MASVS, ref: "MASVS-PRIVACY-1", url: control("MASVS-PRIVACY-1") },
+            { name: MASVS, ref: "MASVS-PRIVACY-3", url: control("MASVS-PRIVACY-3") },
+        ],
+    },
+    {
+        id: "MOB-06",
+        domain: "mobile",
+        title: "The app can require an update",
+        rule: "The app can ask people to update, and refuse to run a version that's no longer safe, so a fix reaches everyone.",
+        why: "Installed apps stay on old versions for years, and without a way to require an update, a security fix never reaches them.",
+        ask: "Can the app require people on an unsafe version to update?",
+        stage: "production",
+        check: "ai-review",
+        severity: "medium",
+        sources: [{ name: MASVS, ref: "MASVS-CODE-2", url: control("MASVS-CODE-2") }],
+    },
+];