diff --git a/.gitignore b/.gitignore index a6fd955..3786278 100644 --- a/.gitignore +++ b/.gitignore @@ -59,6 +59,9 @@ npm-cache/ # Workshop facilitator portraits !public/assets/marketing/workshops/*.png +# How-it-works flow screens (Figma figures) +!public/assets/marketing/how-it-works/*.png + # Open Graph 1200×630 share images (`npm run generate:og-images`) !public/assets/marketing/og-image.png !public/assets/marketing/og-image-templates.png diff --git a/app/(marketing)/how-it-works/_components/HowItWorksGuideBody.tsx b/app/(marketing)/how-it-works/_components/HowItWorksGuideBody.tsx new file mode 100644 index 0000000..bf302bc --- /dev/null +++ b/app/(marketing)/how-it-works/_components/HowItWorksGuideBody.tsx @@ -0,0 +1,297 @@ +import type { ReactNode } from "react"; +import Link from "next/link"; +import Button from "../../../components/buttons/Button"; +import Rule from "../../../components/cards/Rule"; +import type { Category } from "../../../components/cards/Rule"; +import type { ChipOption } from "../../../components/controls/MultiSelect/MultiSelect.types"; +import { + ASSETS, + getAssetPath, + howItWorksFigureAssetPath, +} from "../../../../lib/assetUtils"; +import { + asHowItWorksGuideBlock, + formatHowItWorksByline, + HOW_IT_WORKS_RULE_CARD_ID, + howItWorksReadMinutes, + howItWorksWikiMarkdown, + type HowItWorksGuideBlock, +} from "../../../../lib/howItWorksGuide"; +import type howItWorksPage from "../../../../messages/en/pages/howItWorks.json"; +import HowItWorksShareRow from "./HowItWorksShareRow"; + +type HowItWorksMessages = typeof howItWorksPage; + +const INLINE_LINK = /\[([^\]]+)\]\(([^)]+)\)/g; +const LINK_CLASS = "underline decoration-solid underline-offset-2"; +const ARTICLE_COLUMN_CLASS = + "mx-auto flex w-full flex-col gap-[var(--space-800)] text-[var(--color-content-default-primary)] text-medium-paragraph sm:max-w-[390px] sm:text-large-paragraph md:max-w-[472px] lg:max-w-[700px] lg:text-x-large-paragraph xl:max-w-none xl:text-xx-large-paragraph"; + +function isSafeHref(href: string): boolean { + return ( + href.startsWith("#") || + (href.startsWith("/") && !href.startsWith("//")) || + href.startsWith("https://") || + href.startsWith("http://") || + href.startsWith("mailto:") + ); +} + +function GuideInlineText({ text }: { text: string }) { + const nodes: ReactNode[] = []; + let lastIndex = 0; + let key = 0; + + for (const match of text.matchAll(INLINE_LINK)) { + const matchIndex = match.index ?? 0; + if (matchIndex > lastIndex) { + nodes.push(text.slice(lastIndex, matchIndex)); + } + + const label = match[1]; + const href = match[2]; + if (isSafeHref(href)) { + const isInternal = href.startsWith("/") && !href.startsWith("//"); + nodes.push( + isInternal ? ( + + {label} + + ) : ( + + {label} + + ), + ); + key += 1; + } else { + nodes.push(label); + } + + lastIndex = matchIndex + match[0].length; + } + + if (lastIndex < text.length) { + nodes.push(text.slice(lastIndex)); + } + + return nodes; +} + +function chipsFromLabels(labels: string[]): ChipOption[] { + return labels.map((label) => ({ + id: label.toLowerCase().replace(/[^a-z0-9]+/g, "-"), + label, + state: "unselected" as const, + })); +} + +function teamRuleCategories( + groups: HowItWorksMessages["teamRule"]["categories"], +): Category[] { + return [ + groups.values, + groups.communication, + groups.membership, + groups.decisionMaking, + groups.conflictManagement, + ].map((group) => ({ + name: group.name, + chipOptions: chipsFromLabels(group.chips), + })); +} + +function GuideParagraph({ + lead, + text, +}: { + lead?: string; + text: string; +}) { + return ( +

+ {lead ? {lead} : null} + +

+ ); +} + +function FlowFigure({ + src, + caption, +}: { + src: string; + caption: string; +}) { + return ( +
+
+ {/* eslint-disable-next-line @next/next/no-img-element -- flow screen from Figma; one-sentence caption is the accessible name */} + +
+
+ {caption} +
+
+ ); +} + +function TeamRuleFigure({ + page, +}: { + page: HowItWorksMessages; +}) { + const { teamRule } = page; + return ( +
+
+ + } + /> +
+
+ {teamRule.caption} +
+
+ ); +} + +function GuideBlockView({ + block, + page, + shareUrl, +}: { + block: HowItWorksGuideBlock; + page: HowItWorksMessages; + shareUrl: string; +}) { + if (block.type === "p") { + return ; + } + if (block.type === "figure") { + return ; + } + if (block.type === "ruleFigure") { + return ; + } + if (block.type === "shareRow") { + const wikiMarkdown = howItWorksWikiMarkdown( + page.banner.title, + page.banner.description, + shareUrl, + ); + const mailtoHref = `mailto:?subject=${encodeURIComponent(page.banner.title)}&body=${encodeURIComponent(`${page.banner.title}\n${shareUrl}`)}`; + return ( + + ); + } + return null; +} + +export default function HowItWorksGuideBody({ + page, + shareUrl, +}: { + page: HowItWorksMessages; + shareUrl: string; +}) { + const minutes = howItWorksReadMinutes(page); + const byline = formatHowItWorksByline(page, minutes); + + return ( +
+

+ {byline} + + {page.byline.beforeYouStart} + +

+ + {page.sections.map((section) => { + const blocks = section.blocks.flatMap((block) => { + const guideBlock = asHowItWorksGuideBlock(block); + return guideBlock ? [guideBlock] : []; + }); + const hasCopy = blocks.some((block) => block.type !== "shareRow"); + return ( +
+ {hasCopy ? ( +

+ {section.heading} +

+ ) : null} + {blocks.map((block, index) => ( + + ))} +
+ ); + })} + +
+ + +
+
+ ); +} diff --git a/app/(marketing)/how-it-works/_components/HowItWorksShareRow.tsx b/app/(marketing)/how-it-works/_components/HowItWorksShareRow.tsx new file mode 100644 index 0000000..e3a5173 --- /dev/null +++ b/app/(marketing)/how-it-works/_components/HowItWorksShareRow.tsx @@ -0,0 +1,109 @@ +"use client"; + +import { useCallback, useState } from "react"; +import Alert from "../../../components/modals/Alert"; +import Button from "../../../components/buttons/Button"; +import { HOW_IT_WORKS_RULE_CARD_ID } from "../../../../lib/howItWorksGuide"; + +const CARD_PRINT_STYLE_ID = "how-it-works-card-print"; + +function installCardPrintStyle(): () => void { + document.getElementById(CARD_PRINT_STYLE_ID)?.remove(); + const style = document.createElement("style"); + style.id = CARD_PRINT_STYLE_ID; + style.textContent = `@media print { + body * { visibility: hidden; } + #${HOW_IT_WORKS_RULE_CARD_ID}, + #${HOW_IT_WORKS_RULE_CARD_ID} * { visibility: visible; } + #${HOW_IT_WORKS_RULE_CARD_ID} { + position: absolute; + left: 0; + top: 0; + width: 100%; + } + }`; + document.head.appendChild(style); + return () => style.remove(); +} + +type HowItWorksShareRowProps = { + sendLabel: string; + copyLabel: string; + printLabel: string; + copiedTitle: string; + copyFailedTitle: string; + mailtoHref: string; + wikiMarkdown: string; +}; + +export default function HowItWorksShareRow({ + sendLabel, + copyLabel, + printLabel, + copiedTitle, + copyFailedTitle, + mailtoHref, + wikiMarkdown, +}: HowItWorksShareRowProps) { + const [status, setStatus] = useState<"idle" | "copied" | "failed">("idle"); + + const handleCopy = useCallback(async () => { + try { + await navigator.clipboard.writeText(wikiMarkdown); + setStatus("copied"); + } catch { + setStatus("failed"); + } + }, [wikiMarkdown]); + + const handlePrint = useCallback(() => { + const removeStyle = installCardPrintStyle(); + const cleanup = () => { + removeStyle(); + window.removeEventListener("afterprint", cleanup); + }; + window.addEventListener("afterprint", cleanup); + window.print(); + }, []); + + return ( +
+
+ + + +
+ {status !== "idle" ? ( + setStatus("idle")} + /> + ) : null} +
+ ); +} diff --git a/app/(marketing)/how-it-works/page.tsx b/app/(marketing)/how-it-works/page.tsx index 6c316a4..19d1855 100644 --- a/app/(marketing)/how-it-works/page.tsx +++ b/app/(marketing)/how-it-works/page.tsx @@ -5,7 +5,7 @@ import type { Metadata } from "next"; import dynamic from "next/dynamic"; import messages from "../../../messages/en/index"; -import { getAllBlogPosts } from "../../../lib/content"; +import { getRelatedBlogPosts } from "../../../lib/content"; import { buildHowItWorksSyntheticPost, HOW_IT_WORKS_SENTINEL_SLUG, @@ -15,6 +15,7 @@ import { absoluteSiteUrl, routeMetadata } from "../../../lib/siteMetadata"; import ContentBanner from "../../components/sections/ContentBanner"; import ContentTemplateDecorativeShapes from "../_components/ContentTemplateDecorativeShapes"; import AskOrganizer from "../../components/sections/AskOrganizer"; +import HowItWorksGuideBody from "./_components/HowItWorksGuideBody"; import "../blog/blog.css"; const RelatedArticles = dynamic( @@ -48,10 +49,14 @@ export default async function HowItWorksPage() { const origin = await getRequestSiteOrigin(); const page = messages.pages.howItWorks; const syntheticPost = buildHowItWorksSyntheticPost(page); + const shareUrl = absoluteSiteUrl("/how-it-works", origin); - const allPosts = getAllBlogPosts(); - const relatedPosts = allPosts.slice(0, 8); - const slugOrder = allPosts.map((post) => post.slug); + const relatedPosts = getRelatedBlogPosts( + HOW_IT_WORKS_SENTINEL_SLUG, + page.relatedSlugs, + 3, + ); + const slugOrder = page.relatedSlugs; const askOrganizerData = { title: messages.pages.home.askOrganizer.title, @@ -64,7 +69,7 @@ export default async function HowItWorksPage() { "@type": "WebPage", name: page.banner.title, description: messages.metadata.howItWorks.description, - url: absoluteSiteUrl("/how-it-works", origin), + url: shareUrl, publisher: { "@type": "Organization", name: "CommunityRule", @@ -86,7 +91,7 @@ export default async function HowItWorksPage() { "@type": "ListItem", position: 2, name: page.banner.title, - item: absoluteSiteUrl("/how-it-works", origin), + item: shareUrl, }, ], }; @@ -113,10 +118,7 @@ export default async function HowItWorksPage() {
-
+
diff --git a/app/components/asset/DiagramGlyph/DiagramGlyph.tsx b/app/components/asset/DiagramGlyph/DiagramGlyph.tsx new file mode 100644 index 0000000..e6f02c7 --- /dev/null +++ b/app/components/asset/DiagramGlyph/DiagramGlyph.tsx @@ -0,0 +1,159 @@ +"use client"; + +/** + * Figma: "Asset / Diagram Glyph" (25359:65776) + */ + +import Image from "next/image"; +import { memo } from "react"; +import AdviceGlyph from "./advice.svg"; +import AuthorityGlyph from "./authority.svg"; +import ConflictGlyph from "./conflict.svg"; +import ConsensusGlyph from "./consensus.svg"; +import DiscussionGlyph from "./discussion.svg"; +import GroupGlyph from "./group.svg"; +import LadderGlyph from "./ladder.svg"; +import MembraneGlyph from "./membrane.svg"; +import MoneyGlyph from "./money.svg"; +import PersonGlyph from "./person.svg"; +import PodGlyph from "./pod.svg"; +import PrivacyGlyph from "./privacy.svg"; +import RecordsGlyph from "./records.svg"; +import RotationGlyph from "./rotation.svg"; +import SortitionGlyph from "./sortition.svg"; +import TermGlyph from "./term.svg"; +import VoteGlyph from "./vote.svg"; + +export const DIAGRAM_GLYPH_OPTIONS = [ + "group", + "pod", + "membrane", + "person", + "authority", + "advice", + "rotation", + "ladder", + "conflict", + "consensus", + "vote", + "sortition", + "term", + "discussion", + "records", + "privacy", + "money", +] as const; + +export type DiagramGlyphName = (typeof DIAGRAM_GLYPH_OPTIONS)[number]; + +export const DIAGRAM_GLYPH_SIZE_OPTIONS = [24, 48] as const; +export type DiagramGlyphSize = (typeof DIAGRAM_GLYPH_SIZE_OPTIONS)[number]; + +type SvgComponent = + | React.ComponentType> + | { default: React.ComponentType> }; + +const glyphMap: Record = { + group: GroupGlyph, + pod: PodGlyph, + membrane: MembraneGlyph, + person: PersonGlyph, + authority: AuthorityGlyph, + advice: AdviceGlyph, + rotation: RotationGlyph, + ladder: LadderGlyph, + conflict: ConflictGlyph, + consensus: ConsensusGlyph, + vote: VoteGlyph, + sortition: SortitionGlyph, + term: TermGlyph, + discussion: DiscussionGlyph, + records: RecordsGlyph, + privacy: PrivacyGlyph, + money: MoneyGlyph, +}; + +function resolveSvgComponent(module: SvgComponent) { + if (typeof module === "object" && module !== null && "default" in module) { + return ( + module as { + default: React.ComponentType>; + } + ).default; + } + return module as React.ComponentType>; +} + +export interface DiagramGlyphProps { + glyph: DiagramGlyphName; + className?: string; + /** Width and height. Figma grid is 48; diagrams also use 24. */ + size?: DiagramGlyphSize | number; + /** + * Accessible name when the glyph sits in a diagram. Omit for a decorative + * mark (empty alt / `aria-hidden`). + */ + title?: string; + /** Follows `title` when the glyph is named in a diagram. */ + description?: string; +} + +function DiagramGlyphComponent({ + glyph, + className = "", + size = 48, + title, + description, +}: DiagramGlyphProps) { + const SvgModule = glyphMap[glyph]; + if (!SvgModule) return null; + const resolved = resolveSvgComponent(SvgModule); + const decorative = !title; + const label = [title, description].filter(Boolean).join(". "); + + if (typeof resolved === "string") { + return ( + {decorative + ); + } + + if (resolved == null) return null; + + const Svg = resolved as React.ComponentType>; + + if (decorative) { + return ( + + ); + } + + return ( + + + + ); +} + +const DiagramGlyph = memo(DiagramGlyphComponent); +DiagramGlyph.displayName = "DiagramGlyph"; + +export default DiagramGlyph; diff --git a/app/components/asset/DiagramGlyph/advice.svg b/app/components/asset/DiagramGlyph/advice.svg new file mode 100644 index 0000000..4a5ea4d --- /dev/null +++ b/app/components/asset/DiagramGlyph/advice.svg @@ -0,0 +1,14 @@ + + + + + + + + + + + + + + diff --git a/app/components/asset/DiagramGlyph/authority.svg b/app/components/asset/DiagramGlyph/authority.svg new file mode 100644 index 0000000..5f4a4df --- /dev/null +++ b/app/components/asset/DiagramGlyph/authority.svg @@ -0,0 +1,11 @@ + + + + + + + + + + + diff --git a/app/components/asset/DiagramGlyph/conflict.svg b/app/components/asset/DiagramGlyph/conflict.svg new file mode 100644 index 0000000..f4f9656 --- /dev/null +++ b/app/components/asset/DiagramGlyph/conflict.svg @@ -0,0 +1,11 @@ + + + + + + + + + + + diff --git a/app/components/asset/DiagramGlyph/consensus.svg b/app/components/asset/DiagramGlyph/consensus.svg new file mode 100644 index 0000000..3f6b7fd --- /dev/null +++ b/app/components/asset/DiagramGlyph/consensus.svg @@ -0,0 +1,16 @@ + + + + + + + + + + + + + + + + diff --git a/app/components/asset/DiagramGlyph/discussion.svg b/app/components/asset/DiagramGlyph/discussion.svg new file mode 100644 index 0000000..bb81a3a --- /dev/null +++ b/app/components/asset/DiagramGlyph/discussion.svg @@ -0,0 +1,13 @@ + + + + + + + + + + + + + diff --git a/app/components/asset/DiagramGlyph/group.svg b/app/components/asset/DiagramGlyph/group.svg new file mode 100644 index 0000000..ee69fb3 --- /dev/null +++ b/app/components/asset/DiagramGlyph/group.svg @@ -0,0 +1,11 @@ + + + + + + + + + + + diff --git a/app/components/asset/DiagramGlyph/index.tsx b/app/components/asset/DiagramGlyph/index.tsx new file mode 100644 index 0000000..c2d7b5e --- /dev/null +++ b/app/components/asset/DiagramGlyph/index.tsx @@ -0,0 +1,10 @@ +export { default } from "./DiagramGlyph"; +export { + DIAGRAM_GLYPH_OPTIONS, + DIAGRAM_GLYPH_SIZE_OPTIONS, +} from "./DiagramGlyph"; +export type { + DiagramGlyphName, + DiagramGlyphProps, + DiagramGlyphSize, +} from "./DiagramGlyph"; diff --git a/app/components/asset/DiagramGlyph/ladder.svg b/app/components/asset/DiagramGlyph/ladder.svg new file mode 100644 index 0000000..ccc7ae7 --- /dev/null +++ b/app/components/asset/DiagramGlyph/ladder.svg @@ -0,0 +1,11 @@ + + + + + + + + + + + diff --git a/app/components/asset/DiagramGlyph/membrane.svg b/app/components/asset/DiagramGlyph/membrane.svg new file mode 100644 index 0000000..2a6b1b9 --- /dev/null +++ b/app/components/asset/DiagramGlyph/membrane.svg @@ -0,0 +1,8 @@ + + + + + + + + diff --git a/app/components/asset/DiagramGlyph/money.svg b/app/components/asset/DiagramGlyph/money.svg new file mode 100644 index 0000000..84abdaf --- /dev/null +++ b/app/components/asset/DiagramGlyph/money.svg @@ -0,0 +1,12 @@ + + + + + + + + + + + + diff --git a/app/components/asset/DiagramGlyph/person.svg b/app/components/asset/DiagramGlyph/person.svg new file mode 100644 index 0000000..bafb9dc --- /dev/null +++ b/app/components/asset/DiagramGlyph/person.svg @@ -0,0 +1,11 @@ + + + + + + + + + + + diff --git a/app/components/asset/DiagramGlyph/pod.svg b/app/components/asset/DiagramGlyph/pod.svg new file mode 100644 index 0000000..d650384 --- /dev/null +++ b/app/components/asset/DiagramGlyph/pod.svg @@ -0,0 +1,12 @@ + + + + + + + + + + + + diff --git a/app/components/asset/DiagramGlyph/privacy.svg b/app/components/asset/DiagramGlyph/privacy.svg new file mode 100644 index 0000000..a199b09 --- /dev/null +++ b/app/components/asset/DiagramGlyph/privacy.svg @@ -0,0 +1,12 @@ + + + + + + + + + + + + diff --git a/app/components/asset/DiagramGlyph/records.svg b/app/components/asset/DiagramGlyph/records.svg new file mode 100644 index 0000000..3e06824 --- /dev/null +++ b/app/components/asset/DiagramGlyph/records.svg @@ -0,0 +1,11 @@ + + + + + + + + + + + diff --git a/app/components/asset/DiagramGlyph/rotation.svg b/app/components/asset/DiagramGlyph/rotation.svg new file mode 100644 index 0000000..2684ad1 --- /dev/null +++ b/app/components/asset/DiagramGlyph/rotation.svg @@ -0,0 +1,12 @@ + + + + + + + + + + + + diff --git a/app/components/asset/DiagramGlyph/sortition.svg b/app/components/asset/DiagramGlyph/sortition.svg new file mode 100644 index 0000000..a29138f --- /dev/null +++ b/app/components/asset/DiagramGlyph/sortition.svg @@ -0,0 +1,14 @@ + + + + + + + + + + + + + + diff --git a/app/components/asset/DiagramGlyph/term.svg b/app/components/asset/DiagramGlyph/term.svg new file mode 100644 index 0000000..0686e4f --- /dev/null +++ b/app/components/asset/DiagramGlyph/term.svg @@ -0,0 +1,8 @@ + + + + + + + + diff --git a/app/components/asset/DiagramGlyph/vote.svg b/app/components/asset/DiagramGlyph/vote.svg new file mode 100644 index 0000000..97b4705 --- /dev/null +++ b/app/components/asset/DiagramGlyph/vote.svg @@ -0,0 +1,7 @@ + + + + + + + diff --git a/app/components/asset/PatternGlyph/PatternGlyph.tsx b/app/components/asset/PatternGlyph/PatternGlyph.tsx new file mode 100644 index 0000000..7f3a11b --- /dev/null +++ b/app/components/asset/PatternGlyph/PatternGlyph.tsx @@ -0,0 +1,162 @@ +"use client"; + +/** + * Figma: "Asset / Pattern Glyph" (25449:199) + */ + +import Image from "next/image"; +import { memo } from "react"; +import CircleProcessesGlyph from "./circle-processes.svg"; +import ConflictCouncilGlyph from "./conflict-council.svg"; +import ConsensusApprovalGlyph from "./consensus-approval.svg"; +import ConsensusBuildingGlyph from "./consensus-building.svg"; +import ConsensusSeekingWithDelegatesGlyph from "./consensus-seeking-with-delegates.svg"; +import DeliberativePollingGlyph from "./deliberative-polling.svg"; +import FacilitatedNegotiationGlyph from "./facilitated-negotiation.svg"; +import FullConsensusGlyph from "./full-consensus.svg"; +import LazyConsensusGlyph from "./lazy-consensus.svg"; +import MembershipAgreementGlyph from "./membership-agreement.svg"; +import ModifiedConsensusGlyph from "./modified-consensus.svg"; +import OpenParticipationGlyph from "./open-participation.svg"; +import PeerSponsorshipGlyph from "./peer-sponsorship.svg"; +import ProvisionalMembershipGlyph from "./provisional-membership.svg"; +import ScreenedReferralsGlyph from "./screened-referrals.svg"; +import SociocracyCirclesGlyph from "./sociocracy-circles.svg"; +import TieredMembershipGlyph from "./tiered-membership.svg"; +import TrainingOrOrientationGlyph from "./training-or-orientation.svg"; + +export const PATTERN_GLYPH_OPTIONS = [ + "lazy-consensus", + "full-consensus", + "consensus-seeking-with-delegates", + "modified-consensus", + "sociocracy-circles", + "deliberative-polling", + "open-participation", + "peer-sponsorship", + "consensus-approval", + "provisional-membership", + "membership-agreement", + "training-or-orientation", + "screened-referrals", + "tiered-membership", + "consensus-building", + "facilitated-negotiation", + "conflict-council", + "circle-processes", +] as const; + +export type PatternGlyphName = (typeof PATTERN_GLYPH_OPTIONS)[number]; + +export const PATTERN_GLYPH_SIZE_OPTIONS = [24, 48] as const; +export type PatternGlyphSize = (typeof PATTERN_GLYPH_SIZE_OPTIONS)[number]; + +type SvgComponent = + | React.ComponentType> + | { default: React.ComponentType> }; + +const glyphMap: Record = { + "lazy-consensus": LazyConsensusGlyph, + "full-consensus": FullConsensusGlyph, + "consensus-seeking-with-delegates": ConsensusSeekingWithDelegatesGlyph, + "modified-consensus": ModifiedConsensusGlyph, + "sociocracy-circles": SociocracyCirclesGlyph, + "deliberative-polling": DeliberativePollingGlyph, + "open-participation": OpenParticipationGlyph, + "peer-sponsorship": PeerSponsorshipGlyph, + "consensus-approval": ConsensusApprovalGlyph, + "provisional-membership": ProvisionalMembershipGlyph, + "membership-agreement": MembershipAgreementGlyph, + "training-or-orientation": TrainingOrOrientationGlyph, + "screened-referrals": ScreenedReferralsGlyph, + "tiered-membership": TieredMembershipGlyph, + "consensus-building": ConsensusBuildingGlyph, + "facilitated-negotiation": FacilitatedNegotiationGlyph, + "conflict-council": ConflictCouncilGlyph, + "circle-processes": CircleProcessesGlyph, +}; + +function resolveSvgComponent(module: SvgComponent) { + if (typeof module === "object" && module !== null && "default" in module) { + return ( + module as { + default: React.ComponentType>; + } + ).default; + } + return module as React.ComponentType>; +} + +export interface PatternGlyphProps { + glyph: PatternGlyphName; + className?: string; + /** Width and height. Figma grid is 48; diagrams also use 24. */ + size?: PatternGlyphSize | number; + /** + * Accessible name when the glyph sits in a diagram. Omit for a decorative + * mark (empty alt / `aria-hidden`). + */ + title?: string; + /** Follows `title` when the glyph is named in a diagram. */ + description?: string; +} + +function PatternGlyphComponent({ + glyph, + className = "", + size = 48, + title, + description, +}: PatternGlyphProps) { + const SvgModule = glyphMap[glyph]; + if (!SvgModule) return null; + const resolved = resolveSvgComponent(SvgModule); + const decorative = !title; + const label = [title, description].filter(Boolean).join(". "); + + if (typeof resolved === "string") { + return ( + {decorative + ); + } + + if (resolved == null) return null; + + const Svg = resolved as React.ComponentType>; + + if (decorative) { + return ( + + ); + } + + return ( + + + + ); +} + +const PatternGlyph = memo(PatternGlyphComponent); +PatternGlyph.displayName = "PatternGlyph"; + +export default PatternGlyph; diff --git a/app/components/asset/PatternGlyph/circle-processes.svg b/app/components/asset/PatternGlyph/circle-processes.svg new file mode 100644 index 0000000..fc02ef4 --- /dev/null +++ b/app/components/asset/PatternGlyph/circle-processes.svg @@ -0,0 +1,13 @@ + + + + + + + + + + + + + diff --git a/app/components/asset/PatternGlyph/conflict-council.svg b/app/components/asset/PatternGlyph/conflict-council.svg new file mode 100644 index 0000000..0ac6e4a --- /dev/null +++ b/app/components/asset/PatternGlyph/conflict-council.svg @@ -0,0 +1,12 @@ + + + + + + + + + + + + diff --git a/app/components/asset/PatternGlyph/consensus-approval.svg b/app/components/asset/PatternGlyph/consensus-approval.svg new file mode 100644 index 0000000..97618d5 --- /dev/null +++ b/app/components/asset/PatternGlyph/consensus-approval.svg @@ -0,0 +1,16 @@ + + + + + + + + + + + + + + + + diff --git a/app/components/asset/PatternGlyph/consensus-building.svg b/app/components/asset/PatternGlyph/consensus-building.svg new file mode 100644 index 0000000..02489c5 --- /dev/null +++ b/app/components/asset/PatternGlyph/consensus-building.svg @@ -0,0 +1,10 @@ + + + + + + + + + + diff --git a/app/components/asset/PatternGlyph/consensus-seeking-with-delegates.svg b/app/components/asset/PatternGlyph/consensus-seeking-with-delegates.svg new file mode 100644 index 0000000..4e9da6d --- /dev/null +++ b/app/components/asset/PatternGlyph/consensus-seeking-with-delegates.svg @@ -0,0 +1,9 @@ + + + + + + + + + diff --git a/app/components/asset/PatternGlyph/deliberative-polling.svg b/app/components/asset/PatternGlyph/deliberative-polling.svg new file mode 100644 index 0000000..8a0c204 --- /dev/null +++ b/app/components/asset/PatternGlyph/deliberative-polling.svg @@ -0,0 +1,14 @@ + + + + + + + + + + + + + + diff --git a/app/components/asset/PatternGlyph/facilitated-negotiation.svg b/app/components/asset/PatternGlyph/facilitated-negotiation.svg new file mode 100644 index 0000000..8051c37 --- /dev/null +++ b/app/components/asset/PatternGlyph/facilitated-negotiation.svg @@ -0,0 +1,16 @@ + + + + + + + + + + + + + + + + diff --git a/app/components/asset/PatternGlyph/full-consensus.svg b/app/components/asset/PatternGlyph/full-consensus.svg new file mode 100644 index 0000000..3f6b7fd --- /dev/null +++ b/app/components/asset/PatternGlyph/full-consensus.svg @@ -0,0 +1,16 @@ + + + + + + + + + + + + + + + + diff --git a/app/components/asset/PatternGlyph/index.tsx b/app/components/asset/PatternGlyph/index.tsx new file mode 100644 index 0000000..3adb70b --- /dev/null +++ b/app/components/asset/PatternGlyph/index.tsx @@ -0,0 +1,10 @@ +export { default } from "./PatternGlyph"; +export { + PATTERN_GLYPH_OPTIONS, + PATTERN_GLYPH_SIZE_OPTIONS, +} from "./PatternGlyph"; +export type { + PatternGlyphName, + PatternGlyphProps, + PatternGlyphSize, +} from "./PatternGlyph"; diff --git a/app/components/asset/PatternGlyph/lazy-consensus.svg b/app/components/asset/PatternGlyph/lazy-consensus.svg new file mode 100644 index 0000000..505a7a2 --- /dev/null +++ b/app/components/asset/PatternGlyph/lazy-consensus.svg @@ -0,0 +1,8 @@ + + + + + + + + diff --git a/app/components/asset/PatternGlyph/membership-agreement.svg b/app/components/asset/PatternGlyph/membership-agreement.svg new file mode 100644 index 0000000..22a6b5a --- /dev/null +++ b/app/components/asset/PatternGlyph/membership-agreement.svg @@ -0,0 +1,9 @@ + + + + + + + + + diff --git a/app/components/asset/PatternGlyph/modified-consensus.svg b/app/components/asset/PatternGlyph/modified-consensus.svg new file mode 100644 index 0000000..22817a6 --- /dev/null +++ b/app/components/asset/PatternGlyph/modified-consensus.svg @@ -0,0 +1,8 @@ + + + + + + + + diff --git a/app/components/asset/PatternGlyph/open-participation.svg b/app/components/asset/PatternGlyph/open-participation.svg new file mode 100644 index 0000000..3b0f1b0 --- /dev/null +++ b/app/components/asset/PatternGlyph/open-participation.svg @@ -0,0 +1,5 @@ + + + + + diff --git a/app/components/asset/PatternGlyph/peer-sponsorship.svg b/app/components/asset/PatternGlyph/peer-sponsorship.svg new file mode 100644 index 0000000..94bc04d --- /dev/null +++ b/app/components/asset/PatternGlyph/peer-sponsorship.svg @@ -0,0 +1,8 @@ + + + + + + + + diff --git a/app/components/asset/PatternGlyph/provisional-membership.svg b/app/components/asset/PatternGlyph/provisional-membership.svg new file mode 100644 index 0000000..07be37a --- /dev/null +++ b/app/components/asset/PatternGlyph/provisional-membership.svg @@ -0,0 +1,7 @@ + + + + + + + diff --git a/app/components/asset/PatternGlyph/screened-referrals.svg b/app/components/asset/PatternGlyph/screened-referrals.svg new file mode 100644 index 0000000..159fc16 --- /dev/null +++ b/app/components/asset/PatternGlyph/screened-referrals.svg @@ -0,0 +1,10 @@ + + + + + + + + + + diff --git a/app/components/asset/PatternGlyph/sociocracy-circles.svg b/app/components/asset/PatternGlyph/sociocracy-circles.svg new file mode 100644 index 0000000..fe6efb7 --- /dev/null +++ b/app/components/asset/PatternGlyph/sociocracy-circles.svg @@ -0,0 +1,10 @@ + + + + + + + + + + diff --git a/app/components/asset/PatternGlyph/tiered-membership.svg b/app/components/asset/PatternGlyph/tiered-membership.svg new file mode 100644 index 0000000..04447ab --- /dev/null +++ b/app/components/asset/PatternGlyph/tiered-membership.svg @@ -0,0 +1,9 @@ + + + + + + + + + diff --git a/app/components/asset/PatternGlyph/training-or-orientation.svg b/app/components/asset/PatternGlyph/training-or-orientation.svg new file mode 100644 index 0000000..414850a --- /dev/null +++ b/app/components/asset/PatternGlyph/training-or-orientation.svg @@ -0,0 +1,10 @@ + + + + + + + + + + diff --git a/content/blog/avoiding-burnout-sustainability-in-the-ruins.md b/content/blog/avoiding-burnout-sustainability-in-the-ruins.md index 6d46038..527dffb 100644 --- a/content/blog/avoiding-burnout-sustainability-in-the-ruins.md +++ b/content/blog/avoiding-burnout-sustainability-in-the-ruins.md @@ -54,13 +54,13 @@ Urgency is constant under capitalism. There will always be another crisis, anoth Rest as strategy is the hardest thing to accept because rest isn't something you earn after the work is done. The work is never done. Rest has to be structural, built into how you operate, or it won't happen. -Schedule breaks into your calendar the same way you schedule meetings. Not "take a break when you need it" no one ever needs it until they're already destroyed. Monthly week-long breaks where nothing happens. Quarterly weekend retreats that aren't about work. Built-in downtime between major projects. +Schedule breaks into your calendar the same way you schedule meetings. Not "take a break when you need it." No one ever needs it until they're already destroyed. Monthly week-long breaks where nothing happens. Quarterly weekend retreats that aren't about work. Built-in downtime between major projects. Normalize people being unavailable. If someone says they can't take something on, that's the end of the discussion. No guilt, no pressure, no subtle implications that they're not committed enough. The person who protects their capacity is more valuable than the person who destroys themselves. Building structures for sustainability isn't about being nice to ourselves. It's about building movements that can actually win. That means rotation so knowledge spreads and no one becomes indispensable. That means preserving institutional memory so learning accumulates. That means limiting scope so the work remains possible. That means treating rest as strategy, not weakness. -Rotation means no role is permanent. The person coordinating meetings, managing the budget, maintaining relationships with allied groups, running the communication channels all of it rotates on a set schedule. Six months, a year, whatever makes sense for the role and the group. +Rotation means no role is permanent. The person coordinating meetings, managing the budget, maintaining relationships with allied groups, running the communication channels. All of it rotates on a set schedule. Six months, a year, whatever makes sense for the role and the group. Preserving institutional memory becomes critical when someone burns out and leaves, because they take everything they learned with them. How to navigate specific relationships. What strategies failed before. Why certain decisions were made. The new person starts from zero, makes the same mistakes, learns the same lessons. The group never accumulates knowledge, it just cycles through individuals. diff --git a/content/blog/digital-mediation-and-the-death-of-nuance.md b/content/blog/digital-mediation-and-the-death-of-nuance.md index b6cad4f..f448e8b 100644 --- a/content/blog/digital-mediation-and-the-death-of-nuance.md +++ b/content/blog/digital-mediation-and-the-death-of-nuance.md @@ -14,6 +14,8 @@ background: color: "#FFF1D4" --- +Your organizing group lives in a Discord server. Your mutual aid network coordinates through a Facebook group. Your worker coop runs on Slack. Every conversation, every decision, every conflict gets filtered through platforms designed by corporations to maximize engagement, which is just a polite word for addiction. + This isn't neutral. The medium shapes the message, and algorithmic mediation shapes how we relate to each other in ways that actively undermine the solidarity we're trying to build. Watch what happens in a group chat when someone raises a contentious point. The conversation accelerates. People respond immediately, reacting to the last message without absorbing the whole thread. Nuance disappears. Someone misreads tone, someone else gets defensive, and within twenty minutes you've got a full-blown conflict that wouldn't have happened in a room together. @@ -56,10 +58,6 @@ Stop letting convenience dictate strategy. Yes, everyone's already on Facebook. Learn about alternatives. Research platform coops, explore democratic technology projects, understand what's possible beyond corporate platforms. Support these projects with money and labor when you can. Develop technical literacy within your group. Not everyone needs to code, but someone should understand how your tools work and what the alternatives are. -The anti-social network isn't about rejecting technology. It's about refusing to let corporate platforms mediate all human connection and political organizing. It's about building tools that serve us rather than extract from us. It's about remembering that the most important networks are the ones between actual people, in actual space, building actual power together. - -Your organizing group lives in a Discord server. Your mutual aid network coordinates through a Facebook group. Your worker coop runs on Slack. Every conversation, every decision, every conflict gets filtered through platforms designed by corporations to maximize engagement, which is just a polite word for addiction. - The cooperative model also solves the governance problem. When users control the platform, they can decide collectively what features to build, what data to collect, how to handle moderation. This is democratic technology: tools that serve their users rather than extracting value from them. Use print for things that matter: analysis that took time to develop, information the community needs, calls to action, documentation of victories and lessons. Use it to create physical artifacts of your work that persist beyond the lifespan of any platform. @@ -75,3 +73,5 @@ Technology is shaped by the social relations of its production. Capitalist techn This means investing in democratic alternatives. It means learning technical skills or supporting people who have them. It means treating digital infrastructure as seriously as physical infrastructure. It means refusing to accept that organizing must happen on terms set by corporations. Use print strategically and beautifully. Make things people want to keep and share. Use risograph, xerox, whatever you have access to. The Secret Riso Project shows that small-scale print production can be both accessible and powerful. + +The anti-social network isn't about rejecting technology. It's about refusing to let corporate platforms mediate all human connection and political organizing. It's about building tools that serve us rather than extract from us. It's about remembering that the most important networks are the ones between actual people, in actual space, building actual power together. diff --git a/content/blog/how-chaos-concentrates-control.md b/content/blog/how-chaos-concentrates-control.md index 96a161a..df61a08 100644 --- a/content/blog/how-chaos-concentrates-control.md +++ b/content/blog/how-chaos-concentrates-control.md @@ -38,6 +38,8 @@ Rotating responsibilities prevents the accumulation of informal power. Your grou Name the roles explicitly. Note-taker, treasurer, communications coordinator, whatever you need. Write down what each role does. This isn't about creating a bureaucracy, it's about making power visible so it can be shared. +Rotate them. Six months, a year, whatever makes sense. This prevents anyone from accumulating informal power through being the only person who knows how things work. It also distributes skills across the group. + When someone rotates out, they document what they did and train their replacement. Knowledge can't be hoarded. If only one person understands the finances or the website or the coalition relationships, they have structural power whether you acknowledge it or not. Keep records. Meeting notes, decisions made, rationales discussed. This isn't paranoia, it's memory. Without records, the people who were there control the narrative. @@ -64,12 +66,10 @@ When your worker coop can't make decisions, when your mutual aid network splinte The choice isn't between structure and freedom. It's between explicit structures that can be challenged and changed, and implicit structures that operate in the shadows. One enables democracy. The other prevents it. -Build structures. Make them visible. Change them when they don't work. That's not selling out, that's how you build something that lasts. - Name who can bring proposals and how they get on the agenda. Otherwise the people who are most comfortable speaking up or who talk to the right people beforehand set the agenda by default. -Rotate them. Six months, a year, whatever makes sense. This prevents anyone from accumulating informal power through being the only person who knows how things work. It also distributes skills across the group. - Information access is crucial because hidden information is hidden power. If discussions happen in private chats, if decisions get made in informal hangouts, if context lives in the heads of a few long-timers, you have an invisible hierarchy. Make information accessible. Use shared documents, public channels, whatever works. The point is that anyone in the group can access what they need to participate fully. + +Build structures. Make them visible. Change them when they don't work. That's not selling out, that's how you build something that lasts. diff --git a/content/blog/integrating-new-members-without-dilution.md b/content/blog/integrating-new-members-without-dilution.md index 6237221..fa7c06d 100644 --- a/content/blog/integrating-new-members-without-dilution.md +++ b/content/blog/integrating-new-members-without-dilution.md @@ -34,10 +34,6 @@ This requires the original core to accept that different groups will operate dif Growth means change, and you can't add people without things changing. New people bring new perspectives and energy. If your group can't absorb that, the problem isn't them. -These practices make change manageable. They create structures so integration doesn't depend on heroes working themselves to death. The alternative is slow collapse: your best people burn out, new people drift away, eventually no one's left. - -You need more people. You need them to actually become part of what you're building. This is how. - Staged responsibility means not giving new people important roles immediately. Map which tasks need deep organizational knowledge and which just need someone willing. Coalition negotiations? That needs context. Social media? Less so. Note-taking? Anyone can do it. Month one: observe and take simple tasks. Show up, help with setup, take notes. Month two: join working groups, contribute to discussions, take on contained tasks. Month three onward: more autonomy as understanding deepens. @@ -51,3 +47,7 @@ Document processes, but recognize documentation misses most of what matters. Mee Every few months, talk through key moments: actions that worked, conflicts resolved, important decisions. Make sure newer members hear it. The informal spaces matter too. Pre-meeting chat, post-action talk, group messages. This is where people learn what actually gets valued. Split into smaller working groups with real autonomy. Five to ten people, focused on specific work. They coordinate through assemblies but operate independently. A new person joining a six-person group can be effectively integrated. A new person joining a forty-person meeting just gets lost. + +These practices make change manageable. They create structures so integration doesn't depend on heroes working themselves to death. The alternative is slow collapse: your best people burn out, new people drift away, eventually no one's left. + +You need more people. You need them to actually become part of what you're building. This is how. diff --git a/content/blog/knowledge-management-and-institutional-amnesia.md b/content/blog/knowledge-management-and-institutional-amnesia.md index 3ae1894..11c1f3f 100644 --- a/content/blog/knowledge-management-and-institutional-amnesia.md +++ b/content/blog/knowledge-management-and-institutional-amnesia.md @@ -50,8 +50,6 @@ The point isn't specific tools, it's the principle: use encrypted ephemeral chan Stop treating institutional memory as a luxury you'll get to when things calm down. Things won't calm down. The crisis is permanent under capitalism. Either you build systems that preserve knowledge despite constant turbulence, or you accept endless cycles of reinvention that exhaust everyone involved. -Documentation isn't about bureaucracy. It's about refusing to let hard-won knowledge disappear when it could help the next person trying to do the work. It's about building organizations that can outlast any individual member. It's about sustainability in the ruins. - The critical distinction: these repositories contain procedures, not personal data. Document the how of your work without including identifying information. How to verify requests, how to coordinate pickups, how to handle disputes. The process, not the people. Build redundancy into your system. Multiple members should have access to documentation repositories. Critical information should exist in at least two forms. If the wiki goes down or someone loses the password, you need backup. Consider quarterly reviews where coordinators check that documentation remains current and accessible. @@ -61,3 +59,5 @@ Not everything needs the same security level. Public-facing resources like volun Case-specific details stay in Signal. Personal information stays in Signal. Real-time sensitive coordination stays in Signal. General procedures, lessons learned, organizational structures can move to documentation. The line is whether the information could identify or harm specific people. If yes, it stays ephemeral. If no, it gets preserved. The open source model offers useful parallels here. Successful projects separate community discussion, which happens in ephemeral channels, from documentation, which lives in wikis and readme files. They have contribution guidelines, architecture decisions, and troubleshooting guides that persist. The knowledge exists independently of any individual contributor. When someone leaves, their specific conversations may disappear, but their contributions to understanding how the system works remain. + +Documentation isn't about bureaucracy. It's about refusing to let hard-won knowledge disappear when it could help the next person trying to do the work. It's about building organizations that can outlast any individual member. It's about sustainability in the ruins. diff --git a/docs/figma-component-registry.md b/docs/figma-component-registry.md index 748d3d2..dfeb654 100644 --- a/docs/figma-component-registry.md +++ b/docs/figma-component-registry.md @@ -208,6 +208,8 @@ Full folder map and PNG audit: **[guides/static-assets.md](./guides/static-asset - **Imports:** use **`asset/icon`** (named **`Icon`** component), **`asset/Logo`**, **`asset/Avatar`**, etc.—same rule as **`buttons/Button`**, no top-level **`asset/index.tsx`** barrel. - **`asset/icon/`** — **`Icon.tsx`** maps icon names to SVG modules beside it (`arrow_back.svg`, …); **`index.tsx`** re-exports **`Icon`** and **`ICON_NAME_OPTIONS`** / types. +- **`asset/DiagramGlyph/`** — Figma [**Asset / Diagram Glyph**](https://www.figma.com/design/agv0VBLiBlcnSAaiAORgPR/Community-Rule-System?node-id=25359-65776) (25359:65776). 17 inline SVGs on a 48 viewBox; paths use `currentColor`. +- **`asset/PatternGlyph/`** — Figma [**Asset / Pattern Glyph**](https://www.figma.com/design/agv0VBLiBlcnSAaiAORgPR/Community-Rule-System?node-id=25449-199) (25449:199). 18 zine pattern marks; same `currentColor` contract. - **`public/assets/`** — lowercase kebab-case folders: **`icons/`**, **`logos/`** (incl. **`logos/partners/`**), **`marketing/`**, **`case-study/`**, **`shapes/`**, **`vector/`**, **`template-mark/`**, **`share/`**. Use helpers in **`lib/assetUtils.ts`** (`ASSETS`, `partnerLogoPath`, `vectorMarkPath`, …). - **`public/assets/vector/.svg`** — Figma Asset / Vector marks (same kebab **`slug`** convention as **`public/assets/template-mark/`**). Use **`vectorMarkPath(slug)`**. - **`asset/Logo`** — Community Rule **`Logo`** component (folder PascalCase, like **`Avatar/`**); brand SVG at **`public/assets/logos/community-rule.svg`**. diff --git a/docs/guides/static-assets.md b/docs/guides/static-assets.md index dfb9dff..f066fb7 100644 --- a/docs/guides/static-assets.md +++ b/docs/guides/static-assets.md @@ -11,7 +11,7 @@ public/ icons/ # UI chrome (close, help) + FeatureGrid card glyphs logos/ # Brand + social lockups partners/ # Logo wall partner SVGs (kebab org slug) - marketing/ # Hero, OG share images, feature panels, section numbers, avatars, banners, book cover + marketing/ # Hero, OG share images, feature panels, section numbers, avatars, banners, book cover, how-it-works flow screens case-study/ # CaseStudy card SVG artwork (canonical) shapes/ # Decorative ornaments (stats, quotes, unions, content shapes) vector/ # Use-case group marks diff --git a/lib/assetUtils.ts b/lib/assetUtils.ts index 731c95a..5fd97fb 100644 --- a/lib/assetUtils.ts +++ b/lib/assetUtils.ts @@ -122,6 +122,11 @@ export function featurePanelPath(key: FeaturePanelKey): string { return `assets/marketing/feature-${key}.svg`; } +/** Flow-screen figures on `/how-it-works`. */ +export function howItWorksFigureAssetPath(slug: string): string { + return `assets/marketing/how-it-works/${slug}.png`; +} + /** Feature-grid card glyphs in `public/assets/icons/` (Figma **18632:10668**). */ export type FeatureIconKey = | "git-branch" diff --git a/lib/howItWorksGuide.ts b/lib/howItWorksGuide.ts new file mode 100644 index 0000000..b559e2c --- /dev/null +++ b/lib/howItWorksGuide.ts @@ -0,0 +1,101 @@ +import type howItWorksPage from "../messages/en/pages/howItWorks.json"; + +const HOW_IT_WORKS_WORDS_PER_MINUTE = 200; + +export const HOW_IT_WORKS_RULE_CARD_ID = "how-it-works-rule-card"; + +type HowItWorksMessages = typeof howItWorksPage; + +export type HowItWorksGuideBlock = + | { type: "p"; lead?: string; text: string } + | { type: "figure"; src: string; caption: string } + | { type: "ruleFigure" } + | { type: "shareRow" }; + +const MARKDOWN_LINK = /\[([^\]]+)\]\(([^)]+)\)/g; + +export function asHowItWorksGuideBlock( + block: HowItWorksMessages["sections"][number]["blocks"][number], +): HowItWorksGuideBlock | null { + switch (block.type) { + case "p": + case "figure": + case "ruleFigure": + case "shareRow": + return block as HowItWorksGuideBlock; + default: + return null; + } +} + +export function stripGuideMarkup(text: string): string { + return text.replace(MARKDOWN_LINK, "$1"); +} + +function blockPlainText( + block: HowItWorksGuideBlock, + caption: string, +): string { + if (block.type === "p") { + return [block.lead, block.text].filter(Boolean).join(" "); + } + if (block.type === "figure") { + return block.caption; + } + if (block.type === "ruleFigure") { + return caption; + } + return ""; +} + +/** Visible guide copy used to set the byline read time. */ +export function collectHowItWorksGuideText(page: HowItWorksMessages): string { + const parts: string[] = []; + for (const section of page.sections) { + parts.push(section.heading); + for (const rawBlock of section.blocks) { + const block = asHowItWorksGuideBlock(rawBlock); + if (!block) continue; + parts.push(blockPlainText(block, page.teamRule.caption)); + } + } + return stripGuideMarkup(parts.filter(Boolean).join(" ")); +} + +export function howItWorksReadMinutes(page: HowItWorksMessages): number { + const words = collectHowItWorksGuideText(page) + .trim() + .split(/\s+/) + .filter(Boolean).length; + return Math.max(1, Math.round(words / HOW_IT_WORKS_WORDS_PER_MINUTE)); +} + +export function formatHowItWorksDate(isoDate: string): string { + const date = new Date(`${isoDate}T00:00:00Z`); + return new Intl.DateTimeFormat("en-GB", { + day: "numeric", + month: "long", + year: "numeric", + timeZone: "UTC", + }).format(date); +} + +export function formatHowItWorksByline( + page: HowItWorksMessages, + minutes: number, +): string { + const unit = minutes === 1 ? page.byline.minute : page.byline.minutes; + return page.byline.template + .replace("{author}", page.banner.author) + .replace("{date}", formatHowItWorksDate(page.banner.date)) + .replace("{minutes}", String(minutes)) + .replace("{unit}", unit); +} + +export function howItWorksWikiMarkdown( + title: string, + description: string, + url: string, +): string { + return `[${title}](${url})\n\n${description}`; +} diff --git a/lib/howItWorksSyntheticPost.ts b/lib/howItWorksSyntheticPost.ts index 43208a3..03317ae 100644 --- a/lib/howItWorksSyntheticPost.ts +++ b/lib/howItWorksSyntheticPost.ts @@ -1,5 +1,4 @@ import type { BlogPost } from "./content"; -import { markdownToHtml } from "./content"; import type howItWorksPage from "../messages/en/pages/howItWorks.json"; export const HOW_IT_WORKS_SENTINEL_SLUG = "__how-it-works__"; @@ -8,12 +7,12 @@ type HowItWorksMessages = typeof howItWorksPage; /** * Builds a {@link BlogPost}-shaped object for static marketing pages that reuse - * blog article chrome (`ContentBanner`, `.post-body`) without a markdown file. + * blog article chrome (`ContentBanner`) without a markdown file. */ export function buildHowItWorksSyntheticPost( page: HowItWorksMessages, ): BlogPost { - const { banner, bodyMarkdown } = page; + const { banner } = page; return { slug: HOW_IT_WORKS_SENTINEL_SLUG, @@ -23,8 +22,8 @@ export function buildHowItWorksSyntheticPost( author: banner.author, date: banner.date, }, - content: bodyMarkdown, - htmlContent: markdownToHtml(bodyMarkdown), + content: "", + htmlContent: "", filePath: "messages/en/pages/howItWorks.json", lastModified: new Date(banner.date), }; diff --git a/messages/en/metadata.json b/messages/en/metadata.json index 9e5ff64..2b836b3 100644 --- a/messages/en/metadata.json +++ b/messages/en/metadata.json @@ -148,7 +148,7 @@ } }, "howItWorks": { - "title": "A Guide to CommunityRule", + "title": "When your community sits down to write its Rule", "description": "Sketch your Rule in CommunityRule, then make it your community's own over five short meetings.", "keywords": [ "how it works", diff --git a/messages/en/pages/howItWorks.json b/messages/en/pages/howItWorks.json index 2a4bffb..86ea839 100644 --- a/messages/en/pages/howItWorks.json +++ b/messages/en/pages/howItWorks.json @@ -1,12 +1,374 @@ { + "_comment": "Guide to CommunityRule on /how-it-works. Banner, byline, sections, figures and closing buttons follow the Figma Content page Template frame.", "banner": { - "title": "A Guide to CommunityRule", + "title": "When your community sits down to write its Rule", "description": "Sketch your Rule in CommunityRule, then make it your community's own over five short meetings.", - "author": "CommunityRule", - "date": "2026-01-15" + "author": "CommunityRule Creative Team", + "date": "2027-02-18" + }, + "byline": { + "template": "By {author}. {date}. {minutes} {unit} read. ", + "minute": "minute", + "minutes": "minutes", + "beforeYouStart": "Before you start" }, "relatedArticles": { "title": "Related articles" }, - "bodyMarkdown": "Whether you organize a mutual aid network, manage an open-source project, or run a worker-owned cooperative, unwritten rules are a liability. Implicit structures cause volunteer burnout, endless meetings, and shadow hierarchies where the loudest voices quietly hold the most power.\n\nCommunityRule makes the implicit explicit. It is a modular governance toolkit providing a library of proven patterns that you can mix, match, and export to keep your community safe, equitable, and highly functional.\n\n**How the Platform Works: From Chaos to Clarity**\n\nThe CommunityRule experience is a guided drafting process that takes you from a blank page to a fully functioning governance document.\n\nYou begin by selecting an organizational archetype that matches your mission. The tool then recommends a baseline set of governance patterns. For instance, a mutual aid group receives recommendations prioritized for rapid physical safety, while an open-source project sees patterns optimized for asynchronous code review and protecting maintainer bandwidth.\n\nNext, you customize. You are never locked into a template. You can explore the pattern library to swap out tools, adjust how much authority is granted to different roles, and define your specific safety protocols.\n\nFinally, you export your completed Operating Manual. The platform generates a clean, structured document that you can host on your website, embed in your GitHub repository, or print as a welcome packet for new members. Your group now has a single source of truth.\n\n**The Four Pillars of Governance**\n\nTo build a resilient Operating Manual, you configure settings across four load-bearing pillars. When these are clearly defined, your members are freed from procedural debates and can focus entirely on your shared mission.\n\n**Membership Patterns**\n\nThis pillar defines the boundaries of your community: who is allowed inside, how they join, and what is required to maintain standing.\n\nYou select patterns that align onboarding with your culture. A massive online network might choose an \"Open Access\" pattern to maximize growth, while an activist coalition handling sensitive work might implement \"Exclusionary Vouching,\" requiring new entrants to be personally verified by existing members. Just as importantly, this pillar helps you define clear exit paths. By establishing how members can safely take a leave of absence or transition to an alumni role, you protect the health of the individual and prevent vital institutional knowledge from vanishing when someone burns out.\n\n**Decision-Making Patterns**\n\nThis acts as your organizational engine, defining exactly how proposals turn into executed actions without trapping your group in endless deliberation.\n\nThe key is matching the weight of the decision to the right process. Requiring everyone to vote on daily operations paralyzes a group, but allowing one person to unilaterally change core values destroys trust. You solve this by assigning different patterns to different scopes of work. You might use a \"Do-ocracy\" pattern for administrative tasks, empowering whoever is actually doing the work to make the call without asking permission. For strategic choices, you might implement a \"Supermajority\" pattern, ensuring significant changes have overwhelming buy-in before enactment. This distribution of authority lets your group move fast on the small things and move together on the big things.\n\n**Conflict Management**\n\nConflict is inevitable; toxicity and organizational collapse are preventable. This pillar helps you design repair pathways before a dispute escalates into a crisis.\n\nHealthy communities rely on repair and accountability rather than corporate punishment. You select conflict strategies based on how much external authority is required to solve a problem. For interpersonal friction, \"Restorative Practices\" or \"Peer Mediation\" provide a structured environment and a neutral facilitator, but leave the final resolution to the disputing parties so they co-create their own repair plan. For severe Code of Conduct violations, a \"Conflict Resolution Council\" introduces trusted elders who investigate and issue formal recommendations. Having these patterns pre-selected removes panic and bias from the resolution process.\n\n**Communication Methods**\n\nWhere you talk dictates how you govern. This pillar helps you map your digital and physical infrastructure to ensure you use the right tool for the right conversation.\n\nMixing social banter, secure logistics, and formal voting in one chaotic group chat is a recipe for disaster. You will define the logistics and behavioral norms for each platform your group uses. You might designate Signal strictly for tactical coordination where disappearing messages are mandatory, use Discord for casual onboarding, and reserve a forum like Discourse exclusively for deep, asynchronous policy deliberation.\n\nCrucially, you attach a specific Code of Conduct to each platform to separate minor etiquette from actual harm prevention. Your Code of Conduct establishes zero-tolerance policies for racism, sexism, and bigotry. It explicitly prohibits doxxing, physical intimidation, and the sharing of content that attracts unwanted legal scrutiny, ensuring your communication spaces remain secure and mission-focused." + "relatedSlugs": [ + "resolving-active-conflicts", + "operational-security-mutual-aid", + "making-decisions-without-hierarchy" + ], + "teamRule": { + "title": "CommunityRule Creative Team", + "description": "We build and maintain CommunityRule for the communities that use it. It is free for every community that wants to write down how it decides.", + "caption": "The CommunityRule Creative Team's Rule on one page with its five parts labeled.", + "categories": { + "values": { + "name": "Values", + "chips": [ + "Transparency", + "Forkability", + "Documentation", + "Maintenance", + "Voluntarism" + ] + }, + "communication": { + "name": "Communication", + "chips": [ + "GitHub / GitLab", + "Matrix / Element", + "Email distribution list", + "How we run meetings" + ] + }, + "membership": { + "name": "Membership", + "chips": ["Join by contributing", "Companions"] + }, + "decisionMaking": { + "name": "Decision-making", + "chips": [ + "Consensus decision-making", + "Lazy consensus", + "Do-ocracy", + "Changing this Rule" + ] + }, + "conflictManagement": { + "name": "Conflict management", + "chips": ["Conflict ladder", "Hearing panel", "Restorative practices"] + } + } + }, + "share": { + "send": "Send this to your community", + "copyWiki": "Copy into your wiki", + "print": "Print the card", + "copiedTitle": "Copied to clipboard", + "copyFailedTitle": "Could not copy" + }, + "closing": { + "createRule": "Create rule", + "createRuleHref": "/create/informational", + "downloadKit": "Download the kit", + "downloadKitHref": "/kit" + }, + "sections": [ + { + "id": "what-you-will-have-by-the-end", + "heading": "What you will have by the end", + "blocks": [ + { + "type": "p", + "text": "A Rule is a short document your community can read aloud in a few minutes. It has five parts. The first part names what your community values and the plain signs that a value is slipping. CommunityRule calls those signs signals of violation. The other four parts say how you talk, who belongs, how you decide and what happens when you disagree. Every community has answers to those four already, written or not." + }, + { + "type": "p", + "text": "Here is ours. The CommunityRule Creative Team, the people who build CommunityRule, adopted its own Rule on 30 October 2026. One of its values is Documentation, which pulls against speed. One sign it is slipping is that only one person knows how to deploy. Whoever does the work decides a small change, and anything bigger is approved after 72 hours with no objection." + }, + { + "type": "ruleFigure" + }, + { + "type": "p", + "text": "Nobody starts from a blank page. CommunityRule puts cards in front of your community, drawn from a deck of hundreds, and each card is one way to answer a question. A card is a starting text. Your community can rewrite its words or write a card of its own." + }, + { + "type": "p", + "text": "CommunityRule comes from the Media Economies Design Lab at the University of Colorado Boulder and it is free for every community." + }, + { + "type": "p", + "text": "A Rule is an agreement between people and it sits beside your bylaws if you have them." + } + ] + }, + { + "id": "what-a-rule-costs", + "heading": "What a Rule costs", + "blocks": [ + { + "type": "p", + "text": "A Rule costs five short meetings and at least one real argument. It also costs somebody some quiet power. Somebody has been making decisions the community never handed them and a Rule takes those back. That person will feel it and it may be you." + }, + { + "type": "p", + "text": "A Rule needs upkeep too. Leave it alone and your community has hidden rules again plus a document that says something else." + } + ] + }, + { + "id": "before-you-start", + "heading": "Before you start", + "blocks": [ + { + "type": "p", + "text": "Your community settles five things before anyone sketches. Any member can raise them." + }, + { + "type": "p", + "lead": "Check that your community is not in the middle of a dispute.", + "text": "A community in a dispute cannot write fair rules. Everyone is arguing about an outcome and a Rule is about method. Write it after the dispute and start with [Resolving Active Conflicts](/blog/resolving-active-conflicts) for now." + }, + { + "type": "p", + "lead": "Choose whose email goes in.", + "text": "The tool keeps your place in one browser until someone adds an email. That email becomes the login and only that login can change the Rule later. Use your community's shared inbox if it has one. The Rule stays with whichever email logs in, and deleting that account deletes the Rule. If your community has no shared inbox, choose the person on purpose." + }, + { + "type": "p", + "lead": "Decide where to start.", + "text": "Your community can pick card by card, start from one of the thirteen templates or start from a copy of a Rule another community shared with you. On a template's page choose Customize, which shows the template's cards question by question so your community can change what does not fit. The other button, Use without changes, skips the cards. Changing a template is how a community finds out where it differs." + }, + { + "type": "p", + "lead": "Find what is already written.", + "text": "Bring your bylaws or the pinned message in your chat to the first meeting. The screens take a logo or a photo and no documents, so keep them on the table beside the sketch." + }, + { + "type": "p", + "lead": "Decide what stays out.", + "text": "Leave out rosters, meeting places and legal names if your community's work puts people at risk. Every Rule starts private. Only the people you invite can read it until the person who holds the pen turns on a link. A Rule is public and featured only when a group asks us in writing." + } + ] + }, + { + "id": "sketch-it-in-communityrule", + "heading": "Sketch it in CommunityRule", + "blocks": [ + { + "type": "p", + "text": "The screens are the quick part. One or two people can sketch a whole Rule in one sitting, and nothing is shared until you invite people. Answer for the community you are today and pick what is closest to what you do now. The meetings are where your community decides whether to keep it." + }, + { + "type": "p", + "lead": "1. Say who you are.", + "text": "The first screens ask your community's name, what it does, its kind, how far it reaches, how established it is and how many people have a say in its big decisions. A short screen of yes or no questions follows, such as whether you pay anyone for the work. The answers sort the cards and are never published." + }, + { + "type": "p", + "lead": "2. Add a logo and save your progress.", + "text": "Add your community's logo or a photo, or skip it. Then add the email your community chose. A login link goes to that address so you can come back to the sketch." + }, + { + "type": "p", + "lead": "3. Name your values.", + "text": "Pick the values your community already lives by, up to six, or skip them for now and add them later. Each value asks what it means to your community and how you will know you are not living up to it. The second answer is your signals of violation. Keep a value only if your community can say what breaking it looks like." + }, + { + "type": "figure", + "src": "value-dialog", + "caption": "A value in CommunityRule with one row for what it means and one for the signs it is slipping." + }, + { + "type": "p", + "text": "The four questions come next, each on its own screen of cards. They run how you talk, who belongs, how you decide and what happens when you disagree. The cards suggested for a community like yours come first, tagged Recommended. See all shows the rest with a search, and no card is hidden. Open a card to read the whole policy and change its words. Each question needs at least one card before you move on, and your community can pick more than one." + }, + { + "type": "figure", + "src": "decisions-deck", + "caption": "A screen of cards for how you decide with the suggested cards tagged Recommended." + }, + { + "type": "p", + "lead": "4. Say how you talk.", + "text": "Start with where your community really makes its decisions. Say so if that is the group chat. One card is Signal. Your community coordinates in encrypted Signal groups with messages that disappear on a timer. Another is Code of conduct. One code covers how members treat each other in every channel, meeting and space." + }, + { + "type": "p", + "lead": "5. Say who belongs.", + "text": "The cards cover who can join, how they join and what the community asks of a member. One card is Open admission. Anyone who agrees to follow your Rule can join and start on the work the same day. Another is Vouching. Two members who know someone in person vouch for them before they join. Pick the card closest to what your community did the last time someone asked to join. Leave and return lets a member step back for up to six months and come back without starting over." + }, + { + "type": "p", + "lead": "6. Say how you decide.", + "text": "This question has the most cards. A vote on every small thing stalls a community. One person changing a big thing breaks trust. So pick one card for everyday calls and one for decisions that touch everyone. One card is Do-ocracy. Whoever does the work decides how it gets done. Another is Supermajority rule. A proposal passes only when your community's supermajority share of the active members who vote says yes, such as three quarters. Stop reading cards when one sounds like your last meeting." + }, + { + "type": "p", + "lead": "7. Say what happens when you disagree.", + "text": "One card is Conflict ladder. The two people talk first, then each brings a friend to negotiate, and the people your community names step in last. Another is Conflict working group. Two to five members named in advance hear what the first steps could not settle and propose a plan the members approve. Pick now while nobody is angry." + }, + { + "type": "figure", + "src": "final-review", + "caption": "Final review in CommunityRule with the Rule as one card and a chip for each part." + }, + { + "type": "p", + "lead": "8. Read it through.", + "text": "This screen shows your Rule as one card with a chip for each card and value. Open a chip to change its words or use a section's add chip to pick another card. A question with no card and a card with no words are flagged. Fix each flag before you go on." + }, + { + "type": "p", + "lead": "9. Invite people or finish.", + "text": "Enter an email for each person who should read the Rule, or paste a list. Ask before you add anyone. Each person gets a private link by email and can read the Rule. Only the login your community chose can change it. The Rule and its exports never show names. While the Rule is still a sketch choose Finish without inviting. You can invite everyone from your profile at the last meeting." + }, + { + "type": "p", + "lead": "10. Finish.", + "text": "Your community has a sketch of its Rule. Rules stay private until you share them. Print it or save it as a PDF for the first meeting. A RULE.md file is there for a repo. To change it later, whoever holds the login opens Edit and goes back to the final review." + } + ] + }, + { + "id": "turn-the-sketch-into-your-rule", + "heading": "Turn the sketch into your Rule", + "blocks": [ + { + "type": "p", + "text": "A sketch is not a Rule until your community has argued with it. The kit spreads that argument over five short meetings, each inside a meeting you already hold, and any member can run it. The kit is free for volunteer-run groups and it lives at [communityrule.info/kit](/kit)." + }, + { + "type": "p", + "text": "Before the first meeting book all five and choose who takes the three roles. The facilitator keeps the room on the question and speaks last. The scribe types only what the room agreed and reads it back. The timekeeper calls time. The roles rotate each meeting. Ask everyone to bring one question your community has never asked out loud. Print the worksheets, or use the kit's online board if you meet on a call. Paper is safer for a community whose work puts people at risk." + }, + { + "type": "p", + "text": "Every meeting opens the same way. Someone reads aloud the kit's short rule for how the room decides, before the first proposal. Every meeting closes the same way too. In the last 10 minutes the scribe enters what the room agreed, logged in with the address your community chose, while everyone checks the wording. Nothing else goes into CommunityRule." + }, + { + "type": "p", + "lead": "Meeting 1, 60 minutes.", + "text": "Everyone writes one question your community has never asked out loud, without a name, and the facilitator reads them all. Sort them under the four questions and start with the one that has the most. Spend the rest of the meeting on it. Say how it works now, read what your sketch says and agree what you can." + }, + { + "type": "p", + "lead": "Meetings 2 to 4, 45 minutes each.", + "text": "Take one question each, in whatever order your community chooses. Read back what you agreed last time. Then say how it works now, read what the sketch says and what else you could try and agree what you can. Have more time? Take two questions in one 90-minute meeting." + }, + { + "type": "p", + "lead": "Meeting 5, 45 minutes.", + "text": "Start with values while the room is fresh. For each one say what it looks like when it is slipping. Then someone who wrote the least reads the whole draft aloud. Fix anything that sounds wrong while everyone is there. Agree how the draft reaches every member and when objections close." + }, + { + "type": "p", + "lead": "Send it out.", + "text": "Nothing counts until every member has seen the draft and had time to object. Invite every member from your profile so each gets a private link, and send the draft wherever members actually read, not only the main chat. Objections close the day before your next regular meeting, with at least seven days to respond. That meeting decides any objections the way the draft says. If nobody objects in time the Rule counts. Write down the date it took effect." + } + ] + }, + { + "id": "when-your-community-gets-stuck", + "heading": "When your community gets stuck", + "blocks": [ + { + "type": "p", + "text": "Most meetings stall in one of a few ways and each has a short fix." + }, + { + "type": "p", + "lead": "Your community splits on a card.", + "text": "This is the argument the meetings are for. It costs less now than in the middle of a dispute. Ask what the community did the last time it came up and pick that card. Give the other card a meeting of its own." + }, + { + "type": "p", + "lead": "Nobody knows the answer.", + "text": "Then nobody decided and somebody has been handling it anyway. Ask who dealt with it last time and pick the card closest to what they did. Then ask the community whether to keep doing it that way. Anything your community does not settle can wait and you can add it to your Rule later." + }, + { + "type": "p", + "lead": "Time runs out.", + "text": "Agree what you can, park the rest with a date and keep the full 10 minutes for the close." + }, + { + "type": "p", + "lead": "One or two people do all the talking.", + "text": "Go around the room once before opening it up. The facilitator speaks last." + }, + { + "type": "p", + "lead": "The room starts reliving an old conflict.", + "text": "Bring it back to method. Ask what you would want the Rule to say next time." + }, + { + "type": "p", + "lead": "Only a few people come.", + "text": "Go ahead. Sending the draft out is how everyone else gets a say." + }, + { + "type": "p", + "lead": "Still stuck?", + "text": "Send your question through [Ask an organizer](#ask-organizer). A person will write back within two working days. You can also bring your draft to office hours. The times are at [communityrule.info/kit](/kit)." + } + ] + }, + { + "id": "after-it-counts", + "heading": "After it counts", + "blocks": [ + { + "type": "p", + "lead": "1. Put it where the next new member will find it.", + "text": "That could be the doc new members read or the wall where you meet." + }, + { + "type": "p", + "lead": "2. Use it once on purpose.", + "text": "Open the Rule the next time a decision comes up. Do what it says." + }, + { + "type": "p", + "lead": "3. Set a date to read it again.", + "text": "Read the signals aloud and ask whether anyone has seen one. Change the Rule if someone has." + }, + { + "type": "p", + "lead": "4. Tell us what it changed.", + "text": "Write to us through [Ask an organizer](#ask-organizer)." + } + ] + }, + { + "id": "what-we-are-not-sure-about", + "heading": "What we are not sure about", + "blocks": [ + { + "type": "p", + "text": "We are the lab and the organizers working with it. We rebuilt CommunityRule because of what we learned about the earlier version. Early versions confused people. Many struggled to understand the modules, find the right ones and customize them. Uptake was slow. Many people tried the editor, often alone or in a workshop, and few groups are known to have adopted a Rule and kept it." + }, + { + "type": "p", + "text": "Andy DiLallo rebuilt the tool around what we learned. We think the meetings are the rest of the fix, because a community that argued over its Rule is more likely to keep it. We cannot show that yet." + }, + { + "type": "p", + "text": "Tell us how yours went. The form is called [Ask an organizer](#ask-organizer)." + } + ] + }, + { + "id": "updates-from-groups", + "heading": "Updates from groups", + "blocks": [ + { + "type": "shareRow" + } + ] + } + ] } diff --git a/public/assets/marketing/how-it-works/decisions-deck.png b/public/assets/marketing/how-it-works/decisions-deck.png new file mode 100644 index 0000000..bc0ac3b Binary files /dev/null and b/public/assets/marketing/how-it-works/decisions-deck.png differ diff --git a/public/assets/marketing/how-it-works/final-review.png b/public/assets/marketing/how-it-works/final-review.png new file mode 100644 index 0000000..fb551c4 Binary files /dev/null and b/public/assets/marketing/how-it-works/final-review.png differ diff --git a/public/assets/marketing/how-it-works/value-dialog.png b/public/assets/marketing/how-it-works/value-dialog.png new file mode 100644 index 0000000..81f0a9d Binary files /dev/null and b/public/assets/marketing/how-it-works/value-dialog.png differ diff --git a/stories/asset/DiagramGlyph.stories.js b/stories/asset/DiagramGlyph.stories.js new file mode 100644 index 0000000..acb92f5 --- /dev/null +++ b/stories/asset/DiagramGlyph.stories.js @@ -0,0 +1,78 @@ +import DiagramGlyph, { + DIAGRAM_GLYPH_OPTIONS, + DIAGRAM_GLYPH_SIZE_OPTIONS, +} from "../../app/components/asset/DiagramGlyph"; + +export default { + title: "Components/Asset/DiagramGlyph", + component: DiagramGlyph, + parameters: { + layout: "centered", + docs: { + description: { + component: + "Diagram glyphs from Asset / Diagram Glyph. Paths use currentColor so a parent text class recolors the mark.", + }, + }, + }, + argTypes: { + glyph: { + control: { type: "select" }, + options: [...DIAGRAM_GLYPH_OPTIONS], + }, + size: { + control: { type: "select" }, + options: [...DIAGRAM_GLYPH_SIZE_OPTIONS], + }, + className: { control: "text" }, + title: { control: "text" }, + description: { control: "text" }, + }, +}; + +export const Default = { + args: { + glyph: "group", + size: 48, + className: "text-[var(--color-content-default-primary)]", + }, +}; + +export const Size24 = { + args: { + glyph: "vote", + size: 24, + className: "text-[var(--color-content-default-primary)]", + }, +}; + +export const Recolor = { + args: { + glyph: "consensus", + size: 48, + className: "text-[var(--color-content-default-brand-primary)]", + }, +}; + +export const InDiagram = { + args: { + glyph: "rotation", + size: 48, + className: "text-[var(--color-content-default-primary)]", + title: "Rotation", + description: "Roles move on a set schedule so no one keeps the keys.", + }, +}; + +export const AllGlyphs = { + render: () => ( +
+ {DIAGRAM_GLYPH_OPTIONS.map((glyph) => ( +
+ + {glyph} +
+ ))} +
+ ), +}; diff --git a/stories/asset/PatternGlyph.stories.js b/stories/asset/PatternGlyph.stories.js new file mode 100644 index 0000000..a2f5d7b --- /dev/null +++ b/stories/asset/PatternGlyph.stories.js @@ -0,0 +1,78 @@ +import PatternGlyph, { + PATTERN_GLYPH_OPTIONS, + PATTERN_GLYPH_SIZE_OPTIONS, +} from "../../app/components/asset/PatternGlyph"; + +export default { + title: "Components/Asset/PatternGlyph", + component: PatternGlyph, + parameters: { + layout: "centered", + docs: { + description: { + component: + "Pattern glyphs from the Structure Before Crisis zine. Paths use currentColor so a parent text class recolors the mark.", + }, + }, + }, + argTypes: { + glyph: { + control: { type: "select" }, + options: [...PATTERN_GLYPH_OPTIONS], + }, + size: { + control: { type: "select" }, + options: [...PATTERN_GLYPH_SIZE_OPTIONS], + }, + className: { control: "text" }, + title: { control: "text" }, + description: { control: "text" }, + }, +}; + +export const Default = { + args: { + glyph: "lazy-consensus", + size: 48, + className: "text-[var(--color-content-default-primary)]", + }, +}; + +export const Size24 = { + args: { + glyph: "open-participation", + size: 24, + className: "text-[var(--color-content-default-primary)]", + }, +}; + +export const Recolor = { + args: { + glyph: "full-consensus", + size: 48, + className: "text-[var(--color-content-default-brand-primary)]", + }, +}; + +export const InDiagram = { + args: { + glyph: "conflict-council", + size: 48, + className: "text-[var(--color-content-default-primary)]", + title: "Conflict council", + description: "Named members hear what the first steps could not settle.", + }, +}; + +export const AllGlyphs = { + render: () => ( +
+ {PATTERN_GLYPH_OPTIONS.map((glyph) => ( +
+ + {glyph} +
+ ))} +
+ ), +}; diff --git a/stories/sections/ContentBanner.stories.js b/stories/sections/ContentBanner.stories.js index 8a46968..ba23282 100644 --- a/stories/sections/ContentBanner.stories.js +++ b/stories/sections/ContentBanner.stories.js @@ -24,16 +24,16 @@ const mockBlogPost = { const guidePost = { slug: "__how-it-works__", frontmatter: { - title: "A Guide to CommunityRule", + title: "When your community sits down to write its Rule", description: - "CommunityRule is a modular governance toolkit designed to help democratic groups build, customize, and publish their own Operating Manual.", - author: "CommunityRule", - date: "2026-01-15", + "Sketch your Rule in CommunityRule, then make it your community's own over five short meetings.", + author: "CommunityRule Creative Team", + date: "2027-02-18", }, content: "", htmlContent: "", filePath: "messages/en/pages/howItWorks.json", - lastModified: new Date("2026-01-15"), + lastModified: new Date("2027-02-18"), }; export default { diff --git a/tests/components/DiagramGlyph.test.tsx b/tests/components/DiagramGlyph.test.tsx new file mode 100644 index 0000000..fb886b2 --- /dev/null +++ b/tests/components/DiagramGlyph.test.tsx @@ -0,0 +1,57 @@ +import "@testing-library/jest-dom/vitest"; +import { describe, expect, it } from "vitest"; +import { render, screen } from "@testing-library/react"; +import DiagramGlyph, { + DIAGRAM_GLYPH_OPTIONS, +} from "../../app/components/asset/DiagramGlyph"; + +describe("DiagramGlyph", () => { + it("renders every glyph at 48 and 24", () => { + const { rerender } = render( + , + ); + expect(document.querySelector("svg")).toHaveAttribute("width", "48"); + expect(document.querySelector("svg")).toHaveAttribute("height", "48"); + expect(document.querySelector("svg")).toHaveAttribute("aria-hidden"); + + rerender(); + expect(document.querySelector("svg")).toHaveAttribute("width", "24"); + expect(document.querySelector("svg")).toHaveAttribute("height", "24"); + + for (const glyph of DIAGRAM_GLYPH_OPTIONS) { + rerender(); + expect(document.querySelector("svg")).toBeInTheDocument(); + } + }); + + it("names a diagram glyph and keeps a decorative glyph unlabeled", () => { + const { rerender } = render( + , + ); + expect( + screen.getByRole("img", { + name: "Rotation. Roles move on a set schedule.", + }), + ).toBeInTheDocument(); + + rerender(); + expect(screen.queryByRole("img")).not.toBeInTheDocument(); + expect(document.querySelector("svg")).toHaveAttribute("aria-hidden"); + }); + + it("recolors with one text class", () => { + render( + , + ); + expect(document.querySelector("svg")).toHaveClass( + "text-[var(--color-content-default-brand-primary)]", + ); + }); +}); diff --git a/tests/components/PatternGlyph.test.tsx b/tests/components/PatternGlyph.test.tsx new file mode 100644 index 0000000..9c39a6b --- /dev/null +++ b/tests/components/PatternGlyph.test.tsx @@ -0,0 +1,55 @@ +import "@testing-library/jest-dom/vitest"; +import { describe, expect, it } from "vitest"; +import { render, screen } from "@testing-library/react"; +import PatternGlyph, { + PATTERN_GLYPH_OPTIONS, +} from "../../app/components/asset/PatternGlyph"; + +describe("PatternGlyph", () => { + it("renders every glyph at 48 and 24", () => { + const { rerender } = render( + , + ); + expect(document.querySelector("svg")).toHaveAttribute("width", "48"); + expect(document.querySelector("svg")).toHaveAttribute("aria-hidden"); + + rerender(); + expect(document.querySelector("svg")).toHaveAttribute("width", "24"); + + for (const glyph of PATTERN_GLYPH_OPTIONS) { + rerender(); + expect(document.querySelector("svg")).toBeInTheDocument(); + } + }); + + it("names a diagram glyph and keeps a decorative glyph unlabeled", () => { + const { rerender } = render( + , + ); + expect( + screen.getByRole("img", { + name: "Conflict council. Named members hear what the first steps could not settle.", + }), + ).toBeInTheDocument(); + + rerender(); + expect(screen.queryByRole("img")).not.toBeInTheDocument(); + expect(document.querySelector("svg")).toHaveAttribute("aria-hidden"); + }); + + it("recolors with one text class", () => { + render( + , + ); + expect(document.querySelector("svg")).toHaveClass( + "text-[var(--color-content-default-brand-primary)]", + ); + }); +}); diff --git a/tests/pages/how-it-works-share.test.tsx b/tests/pages/how-it-works-share.test.tsx new file mode 100644 index 0000000..3cb1f73 --- /dev/null +++ b/tests/pages/how-it-works-share.test.tsx @@ -0,0 +1,58 @@ +import "@testing-library/jest-dom/vitest"; +import { describe, expect, it, vi, beforeEach } from "vitest"; +import { fireEvent, waitFor } from "@testing-library/react"; +import { + renderWithProviders as render, + screen, +} from "../utils/test-utils"; +import HowItWorksShareRow from "../../app/(marketing)/how-it-works/_components/HowItWorksShareRow"; + +const writeText = vi.fn().mockResolvedValue(undefined); + +describe("HowItWorksShareRow", () => { + beforeEach(() => { + writeText.mockReset(); + writeText.mockResolvedValue(undefined); + Object.defineProperty(window.navigator, "clipboard", { + configurable: true, + value: { writeText }, + }); + }); + + it("copies wiki markdown and prints only the rule card", async () => { + const print = vi.spyOn(window, "print").mockImplementation(() => {}); + + render( + , + ); + + expect( + screen.getByRole("link", { name: "Send this to your community" }), + ).toHaveAttribute("href", "mailto:?subject=Guide"); + + fireEvent.click( + screen.getByRole("button", { name: "Copy into your wiki" }), + ); + await waitFor(() => { + expect(writeText).toHaveBeenCalledWith("[Guide](https://example.com)"); + }); + expect(screen.getByText("Copied to clipboard")).toBeInTheDocument(); + + fireEvent.click(screen.getByRole("button", { name: "Print the card" })); + expect(print).toHaveBeenCalled(); + const printStyle = document.getElementById("how-it-works-card-print"); + expect(printStyle?.textContent).toContain("#how-it-works-rule-card"); + expect(printStyle?.textContent).toContain("visibility: hidden"); + window.dispatchEvent(new Event("afterprint")); + expect(document.getElementById("how-it-works-card-print")).toBeNull(); + print.mockRestore(); + }); +}); diff --git a/tests/pages/how-it-works.test.jsx b/tests/pages/how-it-works.test.jsx index 464aba6..51c0622 100644 --- a/tests/pages/how-it-works.test.jsx +++ b/tests/pages/how-it-works.test.jsx @@ -3,6 +3,10 @@ import { screen, waitFor } from "@testing-library/react"; import { renderWithProviders as render } from "../utils/test-utils"; import HowItWorksPage from "../../app/(marketing)/how-it-works/page"; import messages from "../../messages/en/index"; +import { + formatHowItWorksByline, + howItWorksReadMinutes, +} from "../../lib/howItWorksGuide"; vi.mock("next/dynamic", () => ({ default: (importFn) => { @@ -13,6 +17,10 @@ vi.mock("next/dynamic", () => ({ }, })); +vi.mock("../../lib/requestSiteOrigin", () => ({ + getRequestSiteOrigin: async () => "https://communityrule.info", +})); + vi.mock("../../app/components/sections/ContentBanner", () => ({ default: ({ post, variant }) => (
@@ -32,11 +40,16 @@ vi.mock("../../app/components/sections/AskOrganizer", () => ({ ), })); +async function renderPage() { + const ui = await HowItWorksPage(); + return render(ui); +} + describe("HowItWorksPage", () => { const page = messages.pages.howItWorks; - test("renders banner, body sections, related articles, and ask organizer", async () => { - render(); + test("renders banner, guide sections, related articles, and ask organizer", async () => { + await renderPage(); expect(screen.getByTestId("content-banner")).toBeInTheDocument(); expect( @@ -48,6 +61,41 @@ describe("HowItWorksPage", () => { ); expect(screen.getByText(page.banner.description)).toBeInTheDocument(); + expect( + screen.getByRole("heading", { name: "What you will have by the end" }), + ).toBeInTheDocument(); + expect( + screen.getByRole("heading", { name: "Sketch it in CommunityRule" }), + ).toBeInTheDocument(); + expect( + screen.getByText(page.teamRule.caption), + ).toBeInTheDocument(); + expect( + screen.getByRole("link", { name: page.closing.createRule }), + ).toHaveAttribute("href", page.closing.createRuleHref); + expect( + screen.getByRole("link", { name: page.closing.downloadKit }), + ).toHaveAttribute("href", page.closing.downloadKitHref); + expect( + screen.getByRole("link", { name: page.byline.beforeYouStart }), + ).toHaveAttribute("href", "#before-you-start"); + expect( + screen.getByText( + formatHowItWorksByline(page, howItWorksReadMinutes(page)).trim(), + { exact: false }, + ), + ).toBeInTheDocument(); + expect( + screen.getByRole("link", { name: "Resolving Active Conflicts" }), + ).toHaveAttribute("href", "/blog/resolving-active-conflicts"); + expect(screen.queryByText(/\[Confirm how long/)).not.toBeInTheDocument(); + expect( + screen.queryByText(/Dated entries from groups/), + ).not.toBeInTheDocument(); + expect( + screen.queryByRole("heading", { name: "Updates from groups" }), + ).not.toBeInTheDocument(); + await waitFor(() => { expect(screen.getByTestId("related-articles")).toBeInTheDocument(); }); @@ -57,15 +105,35 @@ describe("HowItWorksPage", () => { screen.getByText(messages.pages.home.askOrganizer.title), ).toBeInTheDocument(); expect( - screen.getByText(/How the Platform Works: From Chaos to Clarity/), + screen.queryByText(/How the Platform Works: From Chaos to Clarity/), + ).not.toBeInTheDocument(); + expect( + screen.queryByText(/The Four Pillars of Governance/), + ).not.toBeInTheDocument(); + }); + + test("gives each flow screen a one-sentence caption", async () => { + await renderPage(); + + expect( + screen.getByText( + "A value in CommunityRule with one row for what it means and one for the signs it is slipping.", + ), ).toBeInTheDocument(); expect( - screen.getByText(/mutual aid network, manage an open-source project/), + screen.getByText( + "A screen of cards for how you decide with the suggested cards tagged Recommended.", + ), + ).toBeInTheDocument(); + expect( + screen.getByText( + "Final review in CommunityRule with the Rule as one card and a chip for each part.", + ), ).toBeInTheDocument(); }); - test("clips body ornaments at the page frame and keeps them behind copy", () => { - const { container } = render(); + test("clips body ornaments at the page frame and keeps them behind copy", async () => { + const { container } = await renderPage(); const page = container.querySelector("div.min-h-screen"); expect(page).toHaveClass("overflow-x-clip"); diff --git a/tests/unit/howItWorksGuide.test.ts b/tests/unit/howItWorksGuide.test.ts new file mode 100644 index 0000000..2daa281 --- /dev/null +++ b/tests/unit/howItWorksGuide.test.ts @@ -0,0 +1,44 @@ +import { describe, expect, it } from "vitest"; +import messages from "../../messages/en/index"; +import { + collectHowItWorksGuideText, + formatHowItWorksByline, + formatHowItWorksDate, + howItWorksReadMinutes, + howItWorksWikiMarkdown, +} from "../../lib/howItWorksGuide"; + +describe("howItWorksGuide", () => { + const page = messages.pages.howItWorks; + + it("formats the Figma date and byline from the final text", () => { + expect(formatHowItWorksDate(page.banner.date)).toBe("18 February 2027"); + const minutes = howItWorksReadMinutes(page); + expect(minutes).toBeGreaterThanOrEqual(10); + expect(formatHowItWorksByline(page, 1)).toBe( + "By CommunityRule Creative Team. 18 February 2027. 1 minute read. ", + ); + expect(formatHowItWorksByline(page, minutes)).toBe( + `By CommunityRule Creative Team. 18 February 2027. ${minutes} minutes read. `, + ); + const guideText = collectHowItWorksGuideText(page); + expect(guideText).toContain( + "A Rule is a short document your community can read aloud in a few minutes.", + ); + expect(guideText).toContain("Resolving Active Conflicts"); + expect(guideText).not.toContain("](/kit)"); + expect(guideText).not.toMatch(/\[[^\]]*\]/); + }); + + it("builds wiki markdown from the title, description and URL", () => { + expect( + howItWorksWikiMarkdown( + page.banner.title, + page.banner.description, + "https://communityrule.info/how-it-works", + ), + ).toBe( + `[${page.banner.title}](https://communityrule.info/how-it-works)\n\n${page.banner.description}`, + ); + }); +}); diff --git a/tests/unit/learnGuideCopy.test.ts b/tests/unit/learnGuideCopy.test.ts new file mode 100644 index 0000000..0cf3143 --- /dev/null +++ b/tests/unit/learnGuideCopy.test.ts @@ -0,0 +1,109 @@ +import { readFileSync } from "node:fs"; +import path from "node:path"; +import { describe, expect, it } from "vitest"; + +const BLOG_DIR = path.join(process.cwd(), "content/blog"); + +function readGuide(slug: string): string { + return readFileSync(path.join(BLOG_DIR, `${slug}.md`), "utf8"); +} + +function bodyAfterFrontmatter(markdown: string): string { + return markdown.replace(/^---[\s\S]*?---\n*/, "").trim(); +} + +function lastParagraph(markdown: string): string { + const body = bodyAfterFrontmatter(markdown); + const paragraphs = body.split(/\n\n+/).map((paragraph) => paragraph.trim()); + return paragraphs[paragraphs.length - 1] ?? ""; +} + +describe("Learn guide copy", () => { + it("splits the two broken Avoiding Burnout sentences", () => { + const body = bodyAfterFrontmatter( + readGuide("avoiding-burnout-sustainability-in-the-ruins"), + ); + + expect(body).toContain( + `Not "take a break when you need it." No one ever needs it`, + ); + expect(body).not.toContain( + `Not "take a break when you need it" no one ever needs it`, + ); + expect(body).toContain( + "running the communication channels. All of it rotates", + ); + expect(body).not.toContain( + "running the communication channels all of it rotates", + ); + }); + + it("ends How Chaos Concentrates Control on its closing line and keeps Rotate them after the named roles", () => { + const body = bodyAfterFrontmatter(readGuide("how-chaos-concentrates-control")); + const roles = + "Name the roles explicitly. Note-taker, treasurer, communications coordinator, whatever you need."; + const rotateThem = "Rotate them. Six months, a year, whatever makes sense."; + const closing = + "Build structures. Make them visible. Change them when they don't work. That's not selling out, that's how you build something that lasts."; + + expect(body.indexOf(roles)).toBeGreaterThan(-1); + expect(body.indexOf(rotateThem)).toBeGreaterThan(body.indexOf(roles)); + expect(body.indexOf(closing)).toBeGreaterThan(body.indexOf(rotateThem)); + expect(lastParagraph(body)).toBe(closing); + expect(body.indexOf("Name who can bring proposals")).toBeLessThan( + body.indexOf(closing), + ); + expect(body.indexOf("Make information accessible")).toBeLessThan( + body.indexOf(closing), + ); + }); + + it("opens Digital Mediation on the setup and ends on its closing line", () => { + const body = bodyAfterFrontmatter( + readGuide("digital-mediation-and-the-death-of-nuance"), + ); + const setup = "Your organizing group lives in a Discord server."; + const thesis = "This isn't neutral."; + const closing = + "The anti-social network isn't about rejecting technology. It's about refusing to let corporate platforms mediate all human connection and political organizing. It's about building tools that serve us rather than extract from us. It's about remembering that the most important networks are the ones between actual people, in actual space, building actual power together."; + + expect(body.startsWith(setup)).toBe(true); + expect(body.indexOf(thesis)).toBeGreaterThan(body.indexOf(setup)); + expect(lastParagraph(body)).toBe(closing); + }); + + it("ends Knowledge Management on its closing line after the five restored paragraphs", () => { + const body = bodyAfterFrontmatter( + readGuide("knowledge-management-and-institutional-amnesia"), + ); + const firstRestored = + "The critical distinction: these repositories contain procedures, not personal data."; + const lastRestored = + "The open source model offers useful parallels here."; + const closing = + "Documentation isn't about bureaucracy. It's about refusing to let hard-won knowledge disappear when it could help the next person trying to do the work. It's about building organizations that can outlast any individual member. It's about sustainability in the ruins."; + + expect(body.indexOf(firstRestored)).toBeGreaterThan(-1); + expect(body.indexOf(lastRestored)).toBeGreaterThan(body.indexOf(firstRestored)); + expect(body.indexOf(closing)).toBeGreaterThan(body.indexOf(lastRestored)); + expect(lastParagraph(body)).toBe(closing); + }); + + it("moves the Integrating New Members wrap-up after the three sections that followed it", () => { + const body = bodyAfterFrontmatter( + readGuide("integrating-new-members-without-dilution"), + ); + const staged = "Staged responsibility means not giving new people important roles immediately."; + const redundant = "Making knowledge redundant matters because if one person holds crucial knowledge"; + const split = "Split into smaller working groups with real autonomy."; + const wrapUp = "These practices make change manageable."; + const closing = + "You need more people. You need them to actually become part of what you're building. This is how."; + + expect(body.indexOf(staged)).toBeGreaterThan(-1); + expect(body.indexOf(redundant)).toBeGreaterThan(body.indexOf(staged)); + expect(body.indexOf(split)).toBeGreaterThan(body.indexOf(redundant)); + expect(body.indexOf(wrapUp)).toBeGreaterThan(body.indexOf(split)); + expect(lastParagraph(body)).toBe(closing); + }); +});