Onboarding: Semantic-Org/Semantic-UI-React

Generated by RepoPilot · 2026-05-06 · Source

Agent protocol

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/Semantic-Org/Semantic-UI-React shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

Verdict

WAIT — Stale — last commit 1y ago

• 34+ active contributors
• Distributed ownership (top contributor 46% of recent commits)
• MIT licensed
• CI configured
• ⚠ Stale — last commit 1y ago
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

Verify before trusting

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live Semantic-Org/Semantic-UI-React repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/Semantic-Org/Semantic-UI-React.

What it runs against: a local clone of Semantic-Org/Semantic-UI-React — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in Semantic-Org/Semantic-UI-React | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 560 days ago | Catches sudden abandonment since generation |

<details> <summary><b>Run all checks</b> — paste this script from inside your clone of <code>Semantic-Org/Semantic-UI-React</code></summary>

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of Semantic-Org/Semantic-UI-React. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/Semantic-Org/Semantic-UI-React.git
#   cd Semantic-UI-React
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of Semantic-Org/Semantic-UI-React and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "Semantic-Org/Semantic-UI-React(\\.git)?\\b" \\
  && ok "origin remote is Semantic-Org/Semantic-UI-React" \\
  || miss "origin remote is not Semantic-Org/Semantic-UI-React (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "config.js" \\
  && ok "config.js" \\
  || miss "missing critical file: config.js"
test -f ".babelrc" \\
  && ok ".babelrc" \\
  || miss "missing critical file: .babelrc"
test -f "package.json" \\
  && ok "package.json" \\
  || miss "missing critical file: package.json"
test -f ".eslintrc" \\
  && ok ".eslintrc" \\
  || miss "missing critical file: .eslintrc"
test -f ".github/CONTRIBUTING.md" \\
  && ok ".github/CONTRIBUTING.md" \\
  || miss "missing critical file: .github/CONTRIBUTING.md"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 560 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~530d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/Semantic-Org/Semantic-UI-React"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

</details>

TL;DR

Semantic UI React is the official React component library for Semantic UI, providing pre-built, accessible UI components (Button, Modal, Icon, Popup, Sidebar, etc.) that integrate Semantic UI's CSS framework with React's component model. It lets developers build consistent, themeable interfaces without writing custom HTML/CSS for common UI patterns. Standard React component library structure: src/ contains reusable component modules (Button, Modal, Icon, etc.), docs/ holds the documentation site and examples, cypress/ contains integration tests, bundle-size/ tracks tree-shaking efficiency, and .circleci/config.yml + .github/workflows/ define CI pipelines. Each component exports a React functional or class component consuming Semantic UI CSS classes.

Who it's for

React developers building web applications who want production-ready UI components with Semantic UI styling—used at scale by Amazon Publishing, Netflix, and Microsoft Teams. Contributors are React component library maintainers and community members extending the component catalog.

Maturity & risk

Highly mature and production-ready: 1.2M+ lines of JavaScript, active CI/CD via CircleCI and GitHub Actions, codecov integration, size-limit monitoring, and strong community adoption (Amazon, Netflix, Microsoft). Uses release-it for automated versioning and maintains comprehensive test suites (Cypress integration tests visible in cypress/integration/).

Low risk for established users: Semantic UI React has long-term corporate backing and active maintenance. Minor risk: large dependency surface (1.2M+ JS lines suggests many deps), and Semantic UI CSS framework itself is no longer under active development upstream—updates rely on community forks or in-house maintenance.

Active areas of work

Active maintenance with CI checks on every PR (size-limit.yml, pr-health.yml), documentation improvements, and test coverage expansion. CircleCI and GitHub Actions are running builds; .release-it.json indicates automated release tooling is in place.

Get running

git clone https://github.com/Semantic-Org/Semantic-UI-React.git
cd Semantic-UI-React
npm install
npm start  # or check package.json for exact dev script

Daily commands: Exact commands depend on package.json scripts (not fully visible in file list), but typical entry point: npm start for dev server, npm test for Jest/Mocha tests, npm run build for production bundle. Cypress tests run via npm run cypress or similar—see package.json and .circleci/config.yml for precise commands.

Map of the codebase

• config.js — Central build and project configuration file that defines how the library is compiled, packaged, and exported.
• .babelrc — Babel configuration for transpiling React JSX and ES6+ syntax; essential for component compilation.
• package.json — Defines all dependencies, scripts, and library metadata; critical for understanding build pipelines and peer dependencies.
• .eslintrc — Linting rules enforced across the codebase; contributors must follow these standards.
• .github/CONTRIBUTING.md — Development guidelines and contribution workflow; mandatory reading for all contributors.
• cypress.json — End-to-end test configuration; defines how component integration tests are executed.

Components & responsibilities

• UI Components (Button, Icon, Modal, etc.) (React, PropTypes, Semantic UI CSS) — Wrap Semantic UI CSS classes and provide React-friendly props API; handle state for uncontrolled behaviors (modals, sidebars).
  • Failure mode: Broken prop validation, missing classNames, or CSS mismatch causes visual/functional regressions; caught by Cypress tests.
• Build & Transpilation (Babel, config.js, webpack (implied)) — Convert source JSX and ES6+ to distributable JavaScript for npm; generate multiple module formats (ESM, CJS, UMD).
  • Failure mode: Misconfigured Babel presets or entry points produce incorrect bundles; caught by bundle size checks and local testing.
• Test Suite (Cypress) (Cypress, browser automation) — Validate component rendering, user interactions, and visual consistency; prevent regressions on each PR.
  • Failure mode: Flaky tests or missing coverage allows bugs to reach production; mitigated by comprehensive test fixtures in cypress/integration.

Data flow

• Developer code (JSX) → Babel transpiler — Source components written in JSX syntax
• Babel transpiler → Bundler (config.js) — Transpiled JS modules with Semantic UI imports
• Bundler → npm registry — Packaged and versioned component library
• npm registry → Consumer React apps — Downloaded and imported components styled by Semantic UI CSS
• Source components → Cypress test runners — Mount components in test browser environment for E2E validation

How to make changes

Add a new React component

1. Create component file in src/components/{ComponentName}/{ComponentName}.js with React class or functional component following Semantic UI prop patterns (src/components/{ComponentName}/{ComponentName}.js)
2. Define PropTypes or TypeScript interfaces matching Semantic UI component API (src/components/{ComponentName}/{ComponentName}.js)
3. Export component from src/index.js to make it publicly available (src/index.js)
4. Add JSDoc examples and API documentation in docs/ (docs/src/pages/components/{ComponentName}.js)
5. Create Cypress integration test in cypress/integration/{ComponentName}/ (cypress/integration/{ComponentName}/{ComponentName}.spec.js)

Update build configuration or add bundling rule

1. Modify or extend entry points and output settings in config.js (config.js)
2. Adjust Babel transformations if supporting new ES syntax or target environments (.babel-preset.js)
3. Update size constraints in .size-limit.js if bundle grows (.size-limit.js)

Enforce new linting or code style rule

1. Add or modify ESLint rules in .eslintrc (.eslintrc)
2. Define code formatting in .prettierrc.json if spacing/formatting changes (.prettierrc.json)
3. Document in .github/CONTRIBUTING.md so contributors understand the standard (.github/CONTRIBUTING.md)

Why these technologies

• React (with PropTypes/TypeScript) — Official React wrapper for Semantic UI; enables reusable component-driven UI development with type safety.
• Semantic UI CSS — Provides production-ready CSS styling and design system; components wrap it for React integration.
• Babel — Transpiles JSX and modern ES6+ syntax to broadly compatible JavaScript for npm distribution.
• Cypress — Modern E2E testing framework for visual regression and integration testing of React components.
• GitHub Actions — CI/CD automation for testing, linting, bundle size checks, and release workflows.

Trade-offs already made

• Wrapping Semantic UI CSS rather than reimplementing styles

  • Why: Reduces maintenance burden and ensures parity with the design system.
  • Consequence: Requires Semantic UI CSS as a peer dependency; limited control over styling internals.

• Multiple component export formats (ESM, CJS, UMD)

  • Why: Supports diverse consumer environments (modern bundlers, legacy scripts, Node).
  • Consequence: Increased build complexity and larger published package; bundle size monitoring is critical.

• Bundle size limits enforced via size-limit and CI

  • Why: Prevents accidental bloat; keeps library lightweight for web distribution.
  • Consequence: Contributors must optimize or justify size increases; stricter code review for large changes.

Non-goals (don't propose these)

• Does not provide server-side rendering (SSR) utilities beyond standard React support.
• Does not include state management; components are presentational-first.
• Does not offer animation libraries; relies on CSS transitions from Semantic UI.
• Does not implement theming system beyond consuming Semantic UI theme variables.

Anti-patterns to avoid

• Tight coupling to Semantic UI CSS selectors (Medium) — src/components/**/*.js (inferred): Components rely on hardcoded Semantic UI class names; breaking CSS changes require component updates. Mitigated by passing custom className props.
• Uncontrolled component state in modal/sidebar (Low) — cypress/integration/Sidebar/Sidebar.spec.js (example test location): Some components manage internal state (Popup, Sidebar) which can be difficult to test and synchronize; consider controlled prop alternatives.

Performance hotspots

• Cypress test execution in CI (Performance) — E2E test suite runs sequentially; parallelization could speed up PR validation.
• Build output artifacts (Size & Build Time) — Multiple module formats (ESM, CJS, UMD) increase build time and package size; tree-shaking may not fully optimize all formats.
• Documentation generation (undefined) — undefined

Traps & gotchas

No explicit .env or secrets management visible—assume Semantic UI CSS must be installed as a peer dependency (not auto-included). Babel preset at .babel-preset.js may have custom config not visible; verify it handles JSX and modern JS. Bundle size checks (.size-limit.js) may fail on large PRs—understand the impact before adding heavy dependencies. Cypress tests (cypress.json) may require Semantic UI CSS to be available in test fixtures; check cypress/support/index.js for setup.

Architecture

Concepts to learn

• Tree-shaking and bundle analysis — This repo uses bundle-size/ fixtures and size-limit.js to prevent components from bloating the final bundle; understanding ES6 module exports and static imports is critical for keeping a component library lean
• Prop drilling and component composition patterns — React component libraries heavily use composition and controlled/uncontrolled patterns to maximize reusability; Semantic UI React's components must balance flexibility with simplicity
• CSS-in-JS vs. CSS class binding — Semantic UI React does not use CSS-in-JS; instead, it applies Semantic UI CSS classes via className binding, requiring understanding of CSS specificity and class namespacing to avoid conflicts
• Snapshot testing and visual regression — cypress/integration/ includes visual tests (Popup.visual.js); Cypress is used for both functional and visual regression testing to catch unintended UI changes
• Peer dependencies and transitive bundling — Semantic UI React declares Semantic UI and React as peer dependencies (not bundled), reducing duplication when installed alongside other libraries but requiring careful version alignment
• Babel presets and plugin chains — .babelrc and .babel-preset.js define the transpilation pipeline; understanding how Babel plugins compose (JSX → React.createElement, async/await → promises, etc.) is essential for debugging build issues
• CircleCI and GitHub Actions workflows — .circleci/config.yml and .github/workflows/ automate linting, testing, size checks, and releases; understanding CI/CD is necessary to unblock PRs and understand deployment gates

Related repos

• Semantic-Org/Semantic-UI — The upstream CSS framework that semantic-ui-react wraps; understanding its class structure is essential for debugging styling issues
• facebook/react — Core dependency; understanding React's component lifecycle and hooks is foundational to contributing to this library
• material-ui/material-ui — Alternative React component library with similar scope; useful for comparing architecture, test strategies, and documentation patterns
• react-bootstrap/react-bootstrap — Sibling project wrapping Bootstrap instead of Semantic UI; shares similar component API and CI/CD patterns
• Semantic-Org/Semantic-UI-React-Docs — Likely companion repository or documentation site (docs/ folder suggests docs are co-located); check for separate docs-only repo

PR ideas

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add Cypress E2E tests for Popup component with visual regression

The repo has a Popup.visual.js test file in cypress/integration/Popup/ but it appears incomplete. Popup is a critical interactive component with complex positioning logic. A comprehensive Cypress test suite covering trigger types, positioning edge cases, and arrow positioning would catch regressions early and serve as a reference for other component tests.

• [ ] Expand cypress/integration/Popup/Popup.visual.js with tests for all trigger types (click, hover, focus, manual)
• [ ] Add tests for positioning edge cases (viewport boundaries, scrolling containers)
• [ ] Add tests for offset and positioning props interaction
• [ ] Add visual regression snapshots using cypress-image-diff or similar
• [ ] Mirror the pattern in cypress/integration/Sidebar/Sidebar.spec.js for consistency

Add bundle size tracking tests for component combinations in .size-limit.js

The .size-limit.js file exists with fixtures for individual components (Button, Icon, Image, Modal, Portal), but there are no tests for common component combinations (e.g., Form + Input + Button, Table + Pagination). This would catch bloat from unexpected dependency chains and ensure the library remains lightweight for users who import multiple components together.

• [ ] Create new fixture files in bundle-size/fixtures/ for common patterns (e.g., Form.combined.size.js, Modal.withPortal.size.js)
• [ ] Add corresponding entries to .size-limit.js configuration
• [ ] Test realistic import combinations from the docs
• [ ] Document the fixture naming convention in a bundle-size/README.md

Add specific integration tests for accessibility (a11y) features across components

While Cypress tests exist for Popup and Sidebar, there are no dedicated a11y test files. Given that UI components must support ARIA attributes, keyboard navigation, and screen readers, adding axe-core integration tests would ensure compliance and catch regressions in semantic HTML structure.

• [ ] Create cypress/integration/A11y/ directory with shared test utilities
• [ ] Add cypress/integration/A11y/Button.a11y.js testing button roles, keyboard focus, and ARIA states
• [ ] Add cypress/integration/A11y/Modal.a11y.js testing focus trap and keyboard escape
• [ ] Install and configure @axe-core/cypress in cypress/support/index.js
• [ ] Add a shared command in cypress/support/commands.js for running axe checks with consistent rules

Good first issues

• Add missing Cypress integration tests for the Portal component (cypress/integration/Portal/ does not appear in the file list despite Portal being a core component mentioned in bundle-size/fixtures/); contributes test coverage.
• Create TypeScript definitions for frequently-used components in src/ since the repo shows 1,374 lines of TypeScript alongside 1.2M JS—write .d.ts stubs for Button, Modal, and Icon to improve IDE support.
• Audit and document the Babel preset configuration (.babel-preset.js) in docs/, as it's non-obvious how JSX/async-await transforms are applied and would help contributors understanding the build pipeline.

Top contributors

• @layershifter — 46 commits
• @levithomason — 12 commits
• @dominikdosoudil — 7 commits
• @tourman — 2 commits
• @meltyshev — 2 commits

Recent commits

• e0a42b5 — chore(eslint): enable react-hooks/recommended (#4498) (dominikdosoudil)
• a7e8c69 — chore: rename classNameBuilder functions in "views" and remove classNameBuilder aliases with "use" prefix (#4505) (dominikdosoudil)
• 74cbda4 — chore: rename classNameBuilder functions in "collections" (#4502) (dominikdosoudil)
• 791e232 — chore: rename classNameBuilder functions in "elements" (#4503) (dominikdosoudil)
• df42457 — chore: rename classNameBuilder functions in "modules" (#4501) (dominikdosoudil)
• 2dbdc79 — chore: rename classNameBuilder utils from use* -> get* (#4500) (dominikdosoudil)
• 80a60c9 — chore(Popup): replace event-stack (#4499) (dominikdosoudil)
• d70adfc — fix(Popup): fix ability to not hide popup on scroll (#4490) (konradkierus)
• 1623c8d — docs: replace polyfill.io (#4467) (SukkaW)
• 21cce97 — fix(typings): Type Tab.Pane is missing (#4457) (#4473) (atti187)

Security observations

The Semantic-UI-React codebase shows reasonable security practices with proper use of configuration files and build tools. However, the analysis is limited by the absence of the dependency file content (package.json), which is critical for identifying known vulnerabilities in third-party packages. The project uses standard development tools (ESLint, Prettier, CircleCI, GitHub Actions) which support security best practices. No obvious hardcoded secrets were detected in the provided file structure. Main recommendations: (1) Conduct a full dependency audit, (2) Review configuration files for embedded credentials, (3) Ensure test fixtures and configurations don't expose sensitive data, (4) Implement regular security scanning in CI/CD pipeline.

• Medium · Missing Package Dependencies Analysis — package.json, package-lock.json, yarn.lock (not provided). The dependency file content was not provided in the security context. Without analyzing package.json and lock files, it is impossible to identify known vulnerabilities in third-party dependencies, outdated packages, or supply chain risks. Fix: Run 'npm audit' or 'yarn audit' to identify vulnerable dependencies. Regularly update dependencies and use tools like Dependabot to track security updates.
• Low · Configuration Files Exposed — .babelrc, .eslintrc, .circleci/config.yml, cypress.json, .release-it.json. Several configuration files are present in the repository root (.babelrc, .eslintrc, .circleci/config.yml, cypress.json) which may contain sensitive build or deployment information if not properly managed. Fix: Review configuration files to ensure no secrets, API keys, or sensitive tokens are hardcoded. Use environment variables for sensitive configuration. Add sensitive files to .gitignore.
• Low · Public Asset Directory Exposure — docs/public/. The docs/public directory contains multiple image assets that are publicly accessible. While images are generally low-risk, ensure no sensitive metadata or information is embedded in these files. Fix: Verify that public assets do not contain embedded metadata with sensitive information. Use appropriate caching headers and CDN configuration in production.
• Low · Test Configuration File Security — cypress.json, cypress/. cypress.json and cypress/ directory contain test configuration that could reveal application behavior or endpoints if exposed. Fix: Ensure cypress configurations do not contain credentials, API endpoints, or authentication tokens. Use environment variables for test credentials.

LLM-derived; treat as a starting point, not a security audit.

Where to read next

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

---

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.