chore: publish from main

skills/gem-design-md-guidelines/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: gem-design-md-guidelines
+description: Create or review accessible web, desktop, iOS, Android, and cross-platform UI/UX. Use for layouts, themes, components, design systems, DESIGN.md tokens, responsive behavior, dark mode, motion, and WCAG validation.
+---
+
+# UI/UX Design Guidelines
+
+## Workflow
+
+1. Identify purpose, user problem, audience/devices, platform, framework, component library, existing design system/tokens, breakpoints, dark-mode needs, and accessibility constraints.
+2. Select the platform branch below. Apply shared rules plus its requirements.
+3. Preserve established patterns unless the brief requires change. Implement the smallest compliant solution.
+4. Validate tokens, responsive behavior, semantics, keyboard/screen-reader use, contrast, focus, touch targets, states, and reduced motion.
+
+## Platform branches
+
+### Web and desktop
+
+- Use semantic HTML before ARIA; maintain logical focus order, visible focus, and pointer/keyboard parity.
+- Validate breakpoints, readable line lengths, no horizontal overflow, and 44×44px minimum targets.
+- Preserve the component library/layout system; prefer CSS-only motion.
+
+### iOS
+
+- Follow Apple HIG for navigation, system icons, sheets/modals, feedback, and gestures.
+- Handle safe areas, notch/Dynamic Island, status/home indicators, keyboard, and landscape.
+- Support VoiceOver, Dynamic Type, and reduced motion. Targets: ≥44pt with ≥8pt separation.
+- Prefer SF Pro/current system font and system feedback colors; map shared semantic roles to iOS tokens.
+- Use appropriate spring timing; pair haptics with visual or textual feedback.
+
+### Android
+
+- Follow Material 3 for app/navigation bars or rails, FABs, cards, dialogs, navigation, and pressed states.
+- Handle status bars, gesture navigation, keyboard, cutouts, portrait, and landscape.
+- Support TalkBack, font scaling, and reduced motion. Targets: ≥48dp with ≥8dp separation.
+- Prefer Roboto/current system font and Material 3/tokenized colors; use dynamic color only when appropriate.
+- Use elevation/motion tokens and accessible press/state feedback.
+
+### Cross-platform mobile
+
+- Share semantic tokens and content/interaction hierarchy. Map only genuine platform differences (navigation, type, elevation/shadows, safe areas, gestures, system feedback, haptics) through `Platform.select` or a framework adapter; never duplicate whole designs for superficial differences.
+- In React Native, Expo, or Flutter, prefer the current component library/theme, then `StyleSheet.create` or framework theme. Never use inline styles for static values.
+- Support iOS/Android text scaling without clipping or hiding required actions.
+
+### Shared mobile checks
+
+- Use an 8pt grid unless the design system defines a compatible scale.
+- Test cutouts/system bars/home indicators, keyboard overlap, gesture conflicts, reachability, rotation, scrolling, performance, screen-reader order, and large text.
+- Define loading, empty, error, refresh, content, selected, disabled, and active states.
+- Provide framework-required accessibility label, role, hint, and state values.
+
+## `DESIGN.md` compliance
+
+Use Google DESIGN.md alpha format:
+
+1. YAML frontmatter: `version`, `name`, `description`, `colors`, `typography`, `rounded`, `spacing`, `components`.
+2. Canonical prose order: `## Overview`, `## Colors`, `## Typography`, `## Layout`, `## Elevation & Depth`, `## Shapes`, `## Components`, `## Do's and Don'ts`.
+3. Cover brand rationale; semantic palette; type hierarchy; spacing/grid/container widths; surface tiers or flat alternative; radii/borders; component definitions; practical guardrails.
+
+Every YAML `components:` value MUST be a `{token.ref}`—never an inline color, spacing, dimension, or other raw value. Run `npx @google/design.md lint DESIGN.md` when available.
+
+## Frontend Aesthetics
+
+- Ground underspecified briefs in one concrete subject, audience, and primary task. Derive real copy and visual cues from its materials, tools, and vocabulary—not a reusable theme.
+- Choose one coherent direction and one defensible signature element. Concentrate boldness there; keep support restrained and remove purposeless decoration.
+- Make a web hero demonstrate the product's central idea through characteristic content or interaction; avoid canned metric/gradient compositions unless warranted.
+- Use numbering, dividers, labels, and eyebrows only to communicate hierarchy, sequence, or category.
+- Match execution to direction: maximalism needs depth/detail; minimalism needs exact type, spacing, and alignment. Revise anything that could belong to any product.
+- Preserve existing typography, layout, surfaces, effects, components, lists, icons, and navigation by default. Do not reject standard fonts, solid surfaces, or predictable grids without a task-specific reason.
+- Choose a distinctive display/body pair only when required; load fonts through the project approach. Mobile defaults: SF Pro on iOS, Roboto on Android. Use mapped shared fonts only for cross-platform branding (for example, `expo-font`, `react-native-google-fonts`, or embedded assets).
+- Use existing tokens/CSS variables. Apply 60-30-10 only when it fits the design system.
+
+## Color Strategy (Dark Mode)
+
+- Invert surfaces while preserving text contrast; keep accents distinguishable and replace heavy shadows with restrained glow/surface contrast when appropriate.
+- Validate every semantic role in both themes. Share roles across platforms and map them to platform tokens; never hard-code separate palettes.
+- Use OLED true black only when product-appropriate and token-compatible. On Android, use Material 3 dark theme or equivalent tokens.
+
+## Motion & Animation
+
+- Orchestrate page-load motion; do not animate everything. Define consistent durations/easing.
+- Prefer CSS on web/desktop. On mobile, use platform springs or Material tokens and map gesture progress to state.
+- Every nonessential animation MUST support reduced motion by removing, shortening, or replacing movement without losing information or task completion. Haptics MUST NOT be the only feedback.
+
+## Layout Innovation
+
+Allowed when justified: asymmetric grids, controlled overlap/negative margins/z-index, bento or diagonal flow, full-bleed media with contained content, varied-height mobile lists, snap scrolling, reachable floating controls, and safe-area-aware bottom sheets. Keep them responsive, readable, keyboard accessible, and free of unintended horizontal overflow.
+
+## Accessibility and states
+
+- Contrast: ≥4.5:1 normal text; ≥3:1 large text and qualifying UI elements. Focus indicators need sufficient contrast.
+- Use semantic HTML before accurate, necessary ARIA. Ensure keyboard access and logical focus order.
+- Targets: ≥44×44px web/desktop, ≥44pt iOS, ≥48dp Android.
+- Test VoiceOver/TalkBack and text scaling without clipping or hiding essential content.
+- Never communicate through motion alone. Validate empty, loading, error, hover, focus, active, disabled, and selected states.
+
+## Styling Priority
+
+Apply in order:
+
+1. Component-library/global theme configuration.
+2. Library props/themed props (for example NativeBase, React Native Paper, Tamagui).
+3. `StyleSheet.create` (React Native) or framework theme (Flutter), using tokens.
+4. `Platform.select` only for genuine differences such as shadows, fonts, or spacing.
+5. Inline styles only for runtime-dynamic values—NEVER static values.
+
+## Rules
+
+- Greenfield UI defaults to modern, professional, cohesive, responsive, accessible, and distinct. Preserve established visual language and approved handoffs unless explicitly redesigning.
+- Avoid interchangeable card grids, unnecessary containers/pills, gratuitous gradients/glassmorphism, excessive rounding, ornamental icons, filler copy, and decorative motion. Every treatment MUST support hierarchy, brand, affordance, or feedback.
+- Use `DESIGN.md` tokens and `StyleSheet.create`; no hardcoded or static inline styles.

skills/gem-devops-guidelines/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: gem-devops-guidelines
+description: Design or review infrastructure, deployment, CI/CD, Docker, Kubernetes, health checks, rollback, feature flags, production readiness, and mobile release workflows. Use for DevOps, platform, container, pipeline, or release tasks.
+---
+
+# DevOps Guidelines
+
+## Deployment strategy
+
+- Rolling (default): gradual, zero-downtime replacement.
+- Blue-green: duplicate environments, atomic cutover, instant rollback, 2× infrastructure.
+- Canary: route a small percentage first; requires traffic splitting.
+
+## Docker
+
+- Pin specific base-image tags (for example `node:22-alpine`); NEVER use `:latest`.
+- Use multi-stage builds and a non-root user. Copy dependencies first for caching.
+- `.dockerignore`: `node_modules`, `.git`, tests. Define `HEALTHCHECK` and resource limits.
+
+## Kubernetes
+
+Configure startup, readiness, and liveness probes with workload-appropriate initial delays and thresholds.
+
+## CI/CD
+
+- PR: lint → typecheck → unit → integration → preview.
+- Main: build → staging → smoke → production.
+
+## Health and shutdown
+
+- Simple: `GET /health` → `{ "status": "ok" }`.
+- Detailed: dependencies, uptime, version.
+- Services MUST expose meaningful health and gracefully handle `SIGTERM` when the workload requires it.
+
+## Configuration
+
+Use environment variables (Twelve-Factor), separated by environment. Validate at startup and fail fast. NEVER commit secrets or hard-code `NODE_ENV=production`.
+
+## Rollback
+
+Kubernetes: `kubectl rollout undo`. Vercel: `vercel rollback`. Docker: redeploy the previous pinned image.
+
+## Feature Flags
+
+- Lifecycle: create → enable → 5% → 25% → 50% → 100% → remove flag and dead code.
+- Every flag MUST have an owner, expiration, and rollback trigger. Remove within two weeks.
+
+## Checklists
+
+- Pre-deploy, when applicable: passing tests, code review, environment variables, migrations, rollback plan.
+- Post-deploy services: healthy, monitored, old pods terminated, outcome documented.
+- Production services: passing tests; no hardcoded secrets; JSON logs; meaningful health; pinned versions; validated environment variables; resource limits; TLS; CVE scan; CORS; rate limiting; CSP/HSTS/X-Frame-Options; tested rollback; runbook; on-call.
+- Apply security/CVE checks to executable or security-sensitive workloads.
+
+## Mobile Deployment
+
+- EAS: `eas build:configure`; `eas build -p ios|android --profile preview`; `eas update --branch production`; `--auto-submit`.
+- Fastlane: iOS `match`/`cert`/`sigh`/`pilot`; Android Gradle/`supply`.
+- Keep credentials in environment/secret storage, never Git. Automate iOS development/distribution signing with `fastlane match`; use `keytool` and Google Play App Signing for Android.
+- TestFlight: internal instant; external 90 days/100 testers. Google Play: internal/beta/production. Expect 1–7 days for review.
+- Rollback: EAS `eas update:rollback`; native release → revert build; store release → reduce phased rollout.