Political Parlance

Project Overview

Political Parlance is a self-contained, single-file web application providing educational definitions of political science vocabulary for university students, faculty, and the general public. The glossary covers American and global political terms across constitutional concepts, contemporary movements, foreign policy doctrine, electoral mechanics, social justice, economics, media, and political history.

The application is designed as a public-facing academic resource under the Academic Applications brand, intended to be hosted on a university web server and accessed through a browser on any device without requiring installation, login, or server-side processing.

Core design principle: The tool works completely offline once loaded, requires no maintenance infrastructure, and is deployable by uploading a single HTML file. This single-file architecture also makes it the template for a planned family of subject-specific glossaries — African American Studies, Theology, Economics, and others — each reusing the same engine with different content and a distinct visual identity.

The application also includes an AI-powered chatbot assistant in the lower right corner, powered by the Anthropic Claude API, that allows users to ask natural-language questions about the glossary content and receive synthesized responses in real time.

Technology Stack

Language and Runtime

• HTML5 — semantic document structure
• CSS3 — all styling, responsive layout, animations, accessibility states
• Vanilla JavaScript (ES6+) — all application logic; no frameworks or libraries
• Web Speech API — browser-native text-to-speech; no external service required
• Anthropic Claude API — powers the glossary chatbot assistant (requires API key)

Fonts

• Playfair Display (Google Fonts) — masthead title, term names, welcome headings
• Cormorant Garamond (Google Fonts) — masthead subtitle (italic); selected for its distinctive calligraphic italic letterforms
• IBM Plex Serif (Google Fonts) — definition body text
• IBM Plex Mono (Google Fonts) — navigation, labels, badges, controls
• All fonts fall back gracefully to Georgia and system serifs if the CDN is unavailable

No Build Step Required

No npm, no bundler, no server-side language, no build process. Everything lives in a single index.html file and deploys by upload. The only external dependency is the Anthropic API for the chatbot feature, which requires an API key.

File Structure

All three files are uploaded together to the Apache web server directory. The application has no other dependencies beyond network access for Google Fonts and the Anthropic API.

Content Organization

Term Data Structure

All terms are stored as a JavaScript object const DEFS in the script block. Each entry has three fields:

"term key here": {
  "definition": "The definition text...",
  "significance": "Why it matters politically...",
  "example": "Example: A sentence illustrating the term in context."
}

Key Conventions

• Keys are lowercase by default; proper nouns, acronyms, and terms with unconventional casing use their correct form (e.g. DACA, McCarthyism, al-Qaeda, Pan-Africanism)
• Numeric and symbolic keys (e.g. 1619, 9/11, 270) sort into the # bucket
• Multi-word terms use spaces; hyphenated terms preserve hyphens where standard
• Terms beginning with “the” are stored and indexed under T (e.g. the Union, the Black Church)

Title Case Rendering

The titleCase() function renders term names with smart capitalization. A TITLE_OVERRIDES map handles terms with unconventional casing that titleCase cannot resolve automatically (currently: al-Qaeda, McCain-Feingold, McCarthyism, U.S. Territory).

Cross-Reference Linking

When a card is expanded, linkify() scans all three text fields and renders the first occurrence of each glossary term as a clickable link. Rules: multi-word terms always link; single-word terms of 7+ characters link automatically; short terms link only if listed in XREF_SINGLE (acronyms, significant dates). XREF_EXCLUSIONS suppresses links that would be contextually misleading.

Functionality

Navigation

A sticky alpha nav bar provides buttons for # and A–Z, plus a counts toggle that shows or hides per-letter term counts as superscript badges. Clicking an already-active letter collapses and returns to the welcome screen.

Sub-Letter Filter

For buckets with 50+ terms (B, C, D, P, R, S, T), a secondary filter bar appears with two-character sub-groups each labeled with their count. An All button restores the full letter view.

Pagination

Views exceeding 30 terms paginate with ← Previous / Next → controls and a range counter. Navigating to a specific term (via Explore or cross-reference) automatically jumps to the correct page and expands the card.

Search

Live search filters terms as the user types, with an aria-live count announcement. Search bypasses letter nav and sub-filter entirely.

Welcome Screen

Default state showing the Random Term card and About section. The term count badge is a clickable toggle for letter count badges, synchronized with the nav counts button.

Random Term Card

A randomly selected term displays on page load. The term name is clickable and behaves identically to ▶ Explore this term. ↻ New Random Term picks a different term.

Page Title as Home

Clicking Political Parlance in the masthead returns to the welcome screen and simultaneously picks a new random term — the same behavior as New Random Term, making every title click feel like a fresh page experience.

Term Card Layout

Expanded cards have a deliberate four-corner layout: term name (top left), ⌂ Home button (top right), Read Aloud controls (bottom left), × Close (bottom right). A ruled line separates the content from the action bar. On mobile (≤600px) the bottom zone stacks vertically.

Read Aloud

Powered by the browser’s Web Speech API. Reads term name plus all three fields in sequence. Controls include a voice selector (English voices on the device) and speed step buttons (– / +) across seven levels: Slow (0.5×) through Max (2.0×). Speed changes apply in real time by resuming from the last word boundary. Speech stops automatically on close, navigation, or new card open.

Dynamic Term Count & Copyright Year

Both are set at runtime by JavaScript and update automatically as content grows.

Glossary Assistant (Chatbot)

A floating 💬 chat button in the lower right corner opens a panel that allows users to ask natural-language questions about the glossary content. Responses are generated by the Anthropic Claude API using the full glossary as its knowledge base.

How It Works

When a user submits a question, the application sends all 1,030+ term definitions to the Claude API as a system prompt alongside the user’s message. Claude answers from the glossary content, can synthesize across multiple entries, and streams the response word by word into the chat panel.

Features

• Four suggested questions displayed on first open, each clickable to auto-send
• Streaming responses with a typing indicator while the request is in flight
• Conversation history maintained for the session; follow-up questions work naturally
• Clear button resets the conversation
• Auto-growing textarea; Enter sends, Shift+Enter adds a line break
• Graceful error messages if the API is unavailable or the key is not configured

API Key Configuration

The chatbot requires an Anthropic API key to function. The key is stored directly in index.html near the bottom of the file:

const API_KEY = 'YOUR_API_KEY_HERE';

Replace YOUR_API_KEY_HERE with your actual key (beginning sk-ant-) before uploading. Each time a new version of index.html is generated, this step must be repeated. The recommended workflow is a Find & Replace in a text editor.

Security and Cost

Because the API key is embedded in a browser-accessible file, it is technically visible in the page source. For a prototype shared with a small trusted audience this is acceptable. Recommended protections:

• Set a monthly spending limit in the Anthropic console to cap maximum exposure
• Monitor usage in the console’s Cost and Usage pages
• Revoke and replace the key immediately if unexpected usage appears
• For wider public deployment, the proper solution is a server-side proxy that holds the key privately

For a faculty/staff demo, $10–20 in prepaid API credit far exceeds realistic usage. Each chatbot exchange costs a fraction of a cent.

Accessibility

The chat panel uses role="dialog", role="log", aria-live="polite", and full keyboard operability. Focus moves to the input on panel open.

Design System

Aesthetic Direction

The visual design follows an editorial/newspaper aesthetic — formal, serious, and legible — evoking quality print journalism and signaling academic credibility.

Color Palette

All combinations verified at WCAG 2.1 AA contrast ratios:

Typography

• Playfair Display — masthead title, term names, welcome headings
• Cormorant Garamond — masthead subtitle (italic semibold); calligraphic letterforms for elegance at display size
• IBM Plex Serif — definition body text (16px / 1rem)
• IBM Plex Mono — navigation, labels, badges, controls

Responsive Layout

Motion and High Contrast

All transitions disabled via @media (prefers-reduced-motion: reduce). @media (forced-colors: active) supports Windows High Contrast Mode.

Accessibility

Built to conform with WCAG 2.1 Level AA throughout.

Structure and Semantics

• lang="en" on the <html> element; semantic landmarks throughout
• Logical heading hierarchy; screen-reader-only <h2> headings announce letter sections
• Skip link bypasses navigation for keyboard and screen reader users

Keyboard Navigation

• All interactive elements reachable and operable by keyboard
• Cards respond to Enter and Space; focus returns to the card after closing
• All controls (Read Aloud, speed, voice, Close, Home, pagination, sub-filter, chat panel) are keyboard accessible

Screen Reader Support

• aria-expanded, aria-pressed, and aria-label on all interactive elements
• aria-live="polite" regions for search count, pagination range, and chat responses
• Speed buttons announce current speed level; letter buttons announce term counts when visible

Visual

• 3px :focus-visible ring on all interactive elements; suppressed for mouse users
• Minimum 44×44px touch targets; WCAG 2.1 AA contrast ratios throughout

Security

The .htaccess file configures Apache with: HTTPS redirect, Options -Indexes, X-Frame-Options: SAMEORIGIN, X-Content-Type-Options: nosniff, Referrer-Policy, Content Security Policy (self + unsafe-inline + Google Fonts + Anthropic API), Permissions-Policy, and Cache-Control: no-cache. Requires mod_rewrite and mod_headers.

See Section 6 for API key security guidance specific to the chatbot feature.

Content Objectivity

Attribution

Concept, curation, and intellectual property: Malik Singleton.
Definitions researched and composed with the assistance of Claude AI (Anthropic).

Workflow and Collaboration

Development Process

Built through an iterative conversational workflow between Malik Singleton and Claude AI across an extended multi-session process. Stages:

1. Concept and initial build — Architecture, visual design, and first batch of definitions
2. UI iteration — Welcome state, alpha navigation, search, card expand/collapse, Random Term feature
3. Static export — Fully self-contained file with all definitions embedded
4. Responsive and accessible upgrade — Full-width responsive layout and WCAG 2.1 AA
5. Content expansion — Iterative additions across many sessions to 1,030+ terms
6. Cross-reference system — linkify engine with XREF_SINGLE, XREF_EXCLUSIONS, TITLE_OVERRIDES
7. Content consolidation — Redundant entries merged; key naming standardized
8. Read Aloud feature — Web Speech API with voice selector and real-time speed controls
9. Navigation enhancements — Count badges (user-toggled), sub-letter filter, 30-term pagination
10. UX refinements — Clickable title (new random term), clickable featured term name, four-corner card layout, Home button, term count badge as counts toggle
11. Typography upgrade — Cormorant Garamond italic added for subtitle
12. Chatbot assistant — Floating AI panel powered by Claude API with streaming responses
13. Rename — Application renamed from Second Terms to Political Parlance
14. Security — .htaccess configuration for Apache hosting
15. Documentation — This README, updated continuously

Adding New Terms

"your term here": {
  "definition": "The definition text...",
  "significance": "Why it matters politically...",
  "example": "Example: A sentence illustrating the term."
},

Save and re-upload. Term count and letter section update automatically. After each update, remember to restore your API key using Find & Replace (YOUR_API_KEY_HERE → your actual key).

Managing Cross-Reference Exclusions

const XREF_EXCLUSIONS = {
  'your card key': new Set(['false positive term']),
};

Adding Short-Word Cross-References

const XREF_SINGLE = new Set([
  'al-Qaeda', 'LGBTQ', /* ... */
  'your short term',
]);

Adding Display Name Overrides

const TITLE_OVERRIDES = {
  'al-Qaeda': 'al-Qaeda',
  'your term': 'Your Display Name',
};

Scalability and Repurposing

Political Parlance is the first in a planned family of subject-specific glossaries under the Academic Applications brand. The engine and content are distinct layers that separate cleanly.

What Is Reusable

The entire engine — search, navigation, card system, cross-reference linker, read-aloud, pagination, sub-filter, chatbot, accessibility markup, and CSS design system — is completely generic. Approximately 95% of the code can be reused unchanged for any new glossary subject.

What Is Subject-Specific

To create a new glossary: replace the DEFS object, change the title and subtitle copy, and optionally adjust the color palette in :root. The chatbot system prompt should also be updated to reflect the new subject and institution context.

Planned Subject Glossaries

Future Academic Applications glossaries may include African American Studies, Theology, and Economics, each sharing the same engine while serving a distinct academic community.

Template Preparation

When a second glossary is ready to begin, a clean template will be extracted from the current index.html — with DEFS empty, placeholder text throughout, and a comment block explaining what to customize.

Maintenance Guide

Routine Tasks

Hosting Requirements

• Apache web server with mod_rewrite and mod_headers enabled
• HTTPS certificate (standard on university hosting)
• No server-side language or database required
• File size: approximately 1 MB (grows with additional terms)
• Outbound network access required for Google Fonts CDN and Anthropic API

Testing After Updates

• New term appears in the correct letter section
• Card expands correctly with all three fields
• Cross-reference links within the new term’s text work correctly
• Read Aloud reads all three fields; speed controls change rate in real time
• Random Term card can display the new term
• Counts toggle shows the correct count for the new letter
• Chatbot responds to a test question (confirms API key is active)

Contact

For questions about the content or application, contact Malik Singleton through Academic Applications.