@wazir-dev/cli 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +111 -0
- package/CHANGELOG.md +14 -0
- package/CONTRIBUTING.md +101 -0
- package/LICENSE +21 -0
- package/README.md +314 -0
- package/assets/composition-engine.mmd +34 -0
- package/assets/demo-script.sh +17 -0
- package/assets/logo-dark.svg +14 -0
- package/assets/logo.svg +14 -0
- package/assets/pipeline.mmd +39 -0
- package/assets/record-demo.sh +51 -0
- package/docs/README.md +51 -0
- package/docs/adapters/context-mode.md +60 -0
- package/docs/concepts/architecture.md +87 -0
- package/docs/concepts/artifact-model.md +60 -0
- package/docs/concepts/composition-engine.md +36 -0
- package/docs/concepts/indexing-and-recall.md +160 -0
- package/docs/concepts/observability.md +41 -0
- package/docs/concepts/roles-and-workflows.md +59 -0
- package/docs/concepts/terminology-policy.md +27 -0
- package/docs/getting-started/01-installation.md +78 -0
- package/docs/getting-started/02-first-run.md +102 -0
- package/docs/getting-started/03-adding-to-project.md +15 -0
- package/docs/getting-started/04-host-setup.md +15 -0
- package/docs/guides/ci-integration.md +15 -0
- package/docs/guides/creating-skills.md +15 -0
- package/docs/guides/expertise-module-authoring.md +15 -0
- package/docs/guides/hook-development.md +15 -0
- package/docs/guides/memory-and-learnings.md +34 -0
- package/docs/guides/multi-host-export.md +15 -0
- package/docs/guides/troubleshooting.md +101 -0
- package/docs/guides/writing-custom-roles.md +15 -0
- package/docs/plans/2026-03-15-cli-pipeline-integration-design.md +592 -0
- package/docs/plans/2026-03-15-cli-pipeline-integration-plan.md +598 -0
- package/docs/plans/2026-03-15-docs-enforcement-plan.md +238 -0
- package/docs/readmes/INDEX.md +99 -0
- package/docs/readmes/features/expertise/README.md +171 -0
- package/docs/readmes/features/exports/README.md +222 -0
- package/docs/readmes/features/hooks/README.md +103 -0
- package/docs/readmes/features/hooks/loop-cap-guard.md +133 -0
- package/docs/readmes/features/hooks/post-tool-capture.md +121 -0
- package/docs/readmes/features/hooks/post-tool-lint.md +130 -0
- package/docs/readmes/features/hooks/pre-compact-summary.md +122 -0
- package/docs/readmes/features/hooks/pre-tool-capture-route.md +100 -0
- package/docs/readmes/features/hooks/protected-path-write-guard.md +128 -0
- package/docs/readmes/features/hooks/session-start.md +119 -0
- package/docs/readmes/features/hooks/stop-handoff-harvest.md +125 -0
- package/docs/readmes/features/roles/README.md +157 -0
- package/docs/readmes/features/roles/clarifier.md +152 -0
- package/docs/readmes/features/roles/content-author.md +190 -0
- package/docs/readmes/features/roles/designer.md +193 -0
- package/docs/readmes/features/roles/executor.md +184 -0
- package/docs/readmes/features/roles/learner.md +210 -0
- package/docs/readmes/features/roles/planner.md +182 -0
- package/docs/readmes/features/roles/researcher.md +164 -0
- package/docs/readmes/features/roles/reviewer.md +184 -0
- package/docs/readmes/features/roles/specifier.md +162 -0
- package/docs/readmes/features/roles/verifier.md +215 -0
- package/docs/readmes/features/schemas/README.md +178 -0
- package/docs/readmes/features/skills/README.md +63 -0
- package/docs/readmes/features/skills/brainstorming.md +96 -0
- package/docs/readmes/features/skills/debugging.md +148 -0
- package/docs/readmes/features/skills/design.md +120 -0
- package/docs/readmes/features/skills/prepare-next.md +109 -0
- package/docs/readmes/features/skills/run-audit.md +159 -0
- package/docs/readmes/features/skills/scan-project.md +109 -0
- package/docs/readmes/features/skills/self-audit.md +176 -0
- package/docs/readmes/features/skills/tdd.md +137 -0
- package/docs/readmes/features/skills/using-skills.md +92 -0
- package/docs/readmes/features/skills/verification.md +120 -0
- package/docs/readmes/features/skills/writing-plans.md +104 -0
- package/docs/readmes/features/tooling/README.md +320 -0
- package/docs/readmes/features/workflows/README.md +186 -0
- package/docs/readmes/features/workflows/author.md +181 -0
- package/docs/readmes/features/workflows/clarify.md +154 -0
- package/docs/readmes/features/workflows/design-review.md +171 -0
- package/docs/readmes/features/workflows/design.md +169 -0
- package/docs/readmes/features/workflows/discover.md +162 -0
- package/docs/readmes/features/workflows/execute.md +173 -0
- package/docs/readmes/features/workflows/learn.md +167 -0
- package/docs/readmes/features/workflows/plan-review.md +165 -0
- package/docs/readmes/features/workflows/plan.md +170 -0
- package/docs/readmes/features/workflows/prepare-next.md +167 -0
- package/docs/readmes/features/workflows/review.md +169 -0
- package/docs/readmes/features/workflows/run-audit.md +191 -0
- package/docs/readmes/features/workflows/spec-challenge.md +159 -0
- package/docs/readmes/features/workflows/specify.md +160 -0
- package/docs/readmes/features/workflows/verify.md +177 -0
- package/docs/readmes/packages/README.md +50 -0
- package/docs/readmes/packages/ajv.md +117 -0
- package/docs/readmes/packages/context-mode.md +118 -0
- package/docs/readmes/packages/gray-matter.md +116 -0
- package/docs/readmes/packages/node-test.md +137 -0
- package/docs/readmes/packages/yaml.md +112 -0
- package/docs/reference/configuration-reference.md +159 -0
- package/docs/reference/expertise-index.md +52 -0
- package/docs/reference/git-flow.md +43 -0
- package/docs/reference/hooks.md +87 -0
- package/docs/reference/host-exports.md +50 -0
- package/docs/reference/launch-checklist.md +172 -0
- package/docs/reference/marketplace-listings.md +76 -0
- package/docs/reference/release-process.md +34 -0
- package/docs/reference/roles-reference.md +77 -0
- package/docs/reference/skills.md +33 -0
- package/docs/reference/templates.md +29 -0
- package/docs/reference/tooling-cli.md +94 -0
- package/docs/truth-claims.yaml +222 -0
- package/expertise/PROGRESS.md +63 -0
- package/expertise/README.md +18 -0
- package/expertise/antipatterns/PROGRESS.md +56 -0
- package/expertise/antipatterns/backend/api-design-antipatterns.md +1271 -0
- package/expertise/antipatterns/backend/auth-antipatterns.md +1195 -0
- package/expertise/antipatterns/backend/caching-antipatterns.md +622 -0
- package/expertise/antipatterns/backend/database-antipatterns.md +1038 -0
- package/expertise/antipatterns/backend/index.md +24 -0
- package/expertise/antipatterns/backend/microservices-antipatterns.md +850 -0
- package/expertise/antipatterns/code/architecture-antipatterns.md +919 -0
- package/expertise/antipatterns/code/async-antipatterns.md +622 -0
- package/expertise/antipatterns/code/code-smells.md +1186 -0
- package/expertise/antipatterns/code/dependency-antipatterns.md +1209 -0
- package/expertise/antipatterns/code/error-handling-antipatterns.md +1360 -0
- package/expertise/antipatterns/code/index.md +27 -0
- package/expertise/antipatterns/code/naming-and-abstraction.md +1118 -0
- package/expertise/antipatterns/code/state-management-antipatterns.md +1076 -0
- package/expertise/antipatterns/code/testing-antipatterns.md +1053 -0
- package/expertise/antipatterns/design/accessibility-antipatterns.md +1136 -0
- package/expertise/antipatterns/design/dark-patterns.md +1121 -0
- package/expertise/antipatterns/design/index.md +22 -0
- package/expertise/antipatterns/design/ui-antipatterns.md +1202 -0
- package/expertise/antipatterns/design/ux-antipatterns.md +680 -0
- package/expertise/antipatterns/frontend/css-layout-antipatterns.md +691 -0
- package/expertise/antipatterns/frontend/flutter-antipatterns.md +1827 -0
- package/expertise/antipatterns/frontend/index.md +23 -0
- package/expertise/antipatterns/frontend/mobile-antipatterns.md +573 -0
- package/expertise/antipatterns/frontend/react-antipatterns.md +1128 -0
- package/expertise/antipatterns/frontend/spa-antipatterns.md +1235 -0
- package/expertise/antipatterns/index.md +31 -0
- package/expertise/antipatterns/performance/index.md +20 -0
- package/expertise/antipatterns/performance/performance-antipatterns.md +1013 -0
- package/expertise/antipatterns/performance/premature-optimization.md +623 -0
- package/expertise/antipatterns/performance/scaling-antipatterns.md +785 -0
- package/expertise/antipatterns/process/ai-coding-antipatterns.md +853 -0
- package/expertise/antipatterns/process/code-review-antipatterns.md +656 -0
- package/expertise/antipatterns/process/deployment-antipatterns.md +920 -0
- package/expertise/antipatterns/process/index.md +23 -0
- package/expertise/antipatterns/process/technical-debt-antipatterns.md +647 -0
- package/expertise/antipatterns/security/index.md +20 -0
- package/expertise/antipatterns/security/secrets-antipatterns.md +849 -0
- package/expertise/antipatterns/security/security-theater.md +843 -0
- package/expertise/antipatterns/security/vulnerability-patterns.md +801 -0
- package/expertise/architecture/PROGRESS.md +70 -0
- package/expertise/architecture/data/caching-architecture.md +671 -0
- package/expertise/architecture/data/data-consistency.md +574 -0
- package/expertise/architecture/data/data-modeling.md +536 -0
- package/expertise/architecture/data/event-streams-and-queues.md +634 -0
- package/expertise/architecture/data/index.md +25 -0
- package/expertise/architecture/data/search-architecture.md +663 -0
- package/expertise/architecture/data/sql-vs-nosql.md +708 -0
- package/expertise/architecture/decisions/architecture-decision-records.md +640 -0
- package/expertise/architecture/decisions/build-vs-buy.md +616 -0
- package/expertise/architecture/decisions/index.md +23 -0
- package/expertise/architecture/decisions/monolith-to-microservices.md +790 -0
- package/expertise/architecture/decisions/technology-selection.md +616 -0
- package/expertise/architecture/distributed/cap-theorem-and-tradeoffs.md +800 -0
- package/expertise/architecture/distributed/circuit-breaker-bulkhead.md +741 -0
- package/expertise/architecture/distributed/consensus-and-coordination.md +796 -0
- package/expertise/architecture/distributed/distributed-systems-fundamentals.md +564 -0
- package/expertise/architecture/distributed/idempotency-and-retry.md +796 -0
- package/expertise/architecture/distributed/index.md +25 -0
- package/expertise/architecture/distributed/saga-pattern.md +797 -0
- package/expertise/architecture/foundations/architectural-thinking.md +460 -0
- package/expertise/architecture/foundations/coupling-and-cohesion.md +770 -0
- package/expertise/architecture/foundations/design-principles-solid.md +649 -0
- package/expertise/architecture/foundations/domain-driven-design.md +719 -0
- package/expertise/architecture/foundations/index.md +25 -0
- package/expertise/architecture/foundations/separation-of-concerns.md +472 -0
- package/expertise/architecture/foundations/twelve-factor-app.md +797 -0
- package/expertise/architecture/index.md +34 -0
- package/expertise/architecture/integration/api-design-graphql.md +638 -0
- package/expertise/architecture/integration/api-design-grpc.md +804 -0
- package/expertise/architecture/integration/api-design-rest.md +892 -0
- package/expertise/architecture/integration/index.md +25 -0
- package/expertise/architecture/integration/third-party-integration.md +795 -0
- package/expertise/architecture/integration/webhooks-and-callbacks.md +1152 -0
- package/expertise/architecture/integration/websockets-realtime.md +791 -0
- package/expertise/architecture/mobile-architecture/index.md +22 -0
- package/expertise/architecture/mobile-architecture/mobile-app-architecture.md +780 -0
- package/expertise/architecture/mobile-architecture/mobile-backend-for-frontend.md +670 -0
- package/expertise/architecture/mobile-architecture/offline-first.md +719 -0
- package/expertise/architecture/mobile-architecture/push-and-sync.md +782 -0
- package/expertise/architecture/patterns/cqrs-event-sourcing.md +717 -0
- package/expertise/architecture/patterns/event-driven.md +797 -0
- package/expertise/architecture/patterns/hexagonal-clean-architecture.md +870 -0
- package/expertise/architecture/patterns/index.md +27 -0
- package/expertise/architecture/patterns/layered-architecture.md +736 -0
- package/expertise/architecture/patterns/microservices.md +753 -0
- package/expertise/architecture/patterns/modular-monolith.md +692 -0
- package/expertise/architecture/patterns/monolith.md +626 -0
- package/expertise/architecture/patterns/plugin-architecture.md +735 -0
- package/expertise/architecture/patterns/serverless.md +780 -0
- package/expertise/architecture/scaling/database-scaling.md +615 -0
- package/expertise/architecture/scaling/feature-flags-and-rollouts.md +757 -0
- package/expertise/architecture/scaling/horizontal-vs-vertical.md +606 -0
- package/expertise/architecture/scaling/index.md +24 -0
- package/expertise/architecture/scaling/multi-tenancy.md +800 -0
- package/expertise/architecture/scaling/stateless-design.md +787 -0
- package/expertise/backend/embedded-firmware.md +625 -0
- package/expertise/backend/go.md +853 -0
- package/expertise/backend/index.md +24 -0
- package/expertise/backend/java-spring.md +448 -0
- package/expertise/backend/node-typescript.md +625 -0
- package/expertise/backend/python-fastapi.md +724 -0
- package/expertise/backend/rust.md +458 -0
- package/expertise/backend/solidity.md +711 -0
- package/expertise/composition-map.yaml +443 -0
- package/expertise/content/foundations/content-modeling.md +395 -0
- package/expertise/content/foundations/editorial-standards.md +449 -0
- package/expertise/content/foundations/index.md +24 -0
- package/expertise/content/foundations/microcopy.md +455 -0
- package/expertise/content/foundations/terminology-governance.md +509 -0
- package/expertise/content/index.md +34 -0
- package/expertise/content/patterns/accessibility-copy.md +518 -0
- package/expertise/content/patterns/index.md +24 -0
- package/expertise/content/patterns/notification-content.md +433 -0
- package/expertise/content/patterns/sample-content.md +486 -0
- package/expertise/content/patterns/state-copy.md +439 -0
- package/expertise/design/PROGRESS.md +58 -0
- package/expertise/design/disciplines/dark-mode-theming.md +577 -0
- package/expertise/design/disciplines/design-systems.md +595 -0
- package/expertise/design/disciplines/index.md +25 -0
- package/expertise/design/disciplines/information-architecture.md +800 -0
- package/expertise/design/disciplines/interaction-design.md +788 -0
- package/expertise/design/disciplines/responsive-design.md +552 -0
- package/expertise/design/disciplines/usability-testing.md +516 -0
- package/expertise/design/disciplines/user-research.md +792 -0
- package/expertise/design/foundations/accessibility-design.md +796 -0
- package/expertise/design/foundations/color-theory.md +797 -0
- package/expertise/design/foundations/iconography.md +795 -0
- package/expertise/design/foundations/index.md +26 -0
- package/expertise/design/foundations/motion-and-animation.md +653 -0
- package/expertise/design/foundations/rtl-design.md +585 -0
- package/expertise/design/foundations/spacing-and-layout.md +607 -0
- package/expertise/design/foundations/typography.md +800 -0
- package/expertise/design/foundations/visual-hierarchy.md +761 -0
- package/expertise/design/index.md +32 -0
- package/expertise/design/patterns/authentication-flows.md +474 -0
- package/expertise/design/patterns/content-consumption.md +789 -0
- package/expertise/design/patterns/data-display.md +618 -0
- package/expertise/design/patterns/e-commerce.md +1494 -0
- package/expertise/design/patterns/feedback-and-states.md +642 -0
- package/expertise/design/patterns/forms-and-input.md +819 -0
- package/expertise/design/patterns/gamification.md +801 -0
- package/expertise/design/patterns/index.md +31 -0
- package/expertise/design/patterns/microinteractions.md +449 -0
- package/expertise/design/patterns/navigation.md +800 -0
- package/expertise/design/patterns/notifications.md +705 -0
- package/expertise/design/patterns/onboarding.md +700 -0
- package/expertise/design/patterns/search-and-filter.md +601 -0
- package/expertise/design/patterns/settings-and-preferences.md +768 -0
- package/expertise/design/patterns/social-and-community.md +748 -0
- package/expertise/design/platforms/desktop-native.md +612 -0
- package/expertise/design/platforms/index.md +25 -0
- package/expertise/design/platforms/mobile-android.md +825 -0
- package/expertise/design/platforms/mobile-cross-platform.md +983 -0
- package/expertise/design/platforms/mobile-ios.md +699 -0
- package/expertise/design/platforms/tablet.md +794 -0
- package/expertise/design/platforms/web-dashboard.md +790 -0
- package/expertise/design/platforms/web-responsive.md +550 -0
- package/expertise/design/psychology/behavioral-nudges.md +449 -0
- package/expertise/design/psychology/cognitive-load.md +1191 -0
- package/expertise/design/psychology/error-psychology.md +778 -0
- package/expertise/design/psychology/index.md +22 -0
- package/expertise/design/psychology/persuasive-design.md +736 -0
- package/expertise/design/psychology/user-mental-models.md +623 -0
- package/expertise/design/tooling/open-pencil.md +266 -0
- package/expertise/frontend/angular.md +1073 -0
- package/expertise/frontend/desktop-electron.md +546 -0
- package/expertise/frontend/flutter.md +782 -0
- package/expertise/frontend/index.md +27 -0
- package/expertise/frontend/native-android.md +409 -0
- package/expertise/frontend/native-ios.md +490 -0
- package/expertise/frontend/react-native.md +1160 -0
- package/expertise/frontend/react.md +808 -0
- package/expertise/frontend/vue.md +1089 -0
- package/expertise/humanize/domain-rules-code.md +79 -0
- package/expertise/humanize/domain-rules-content.md +67 -0
- package/expertise/humanize/domain-rules-technical-docs.md +56 -0
- package/expertise/humanize/index.md +35 -0
- package/expertise/humanize/self-audit-checklist.md +87 -0
- package/expertise/humanize/sentence-patterns.md +218 -0
- package/expertise/humanize/vocabulary-blacklist.md +105 -0
- package/expertise/i18n/PROGRESS.md +65 -0
- package/expertise/i18n/advanced/accessibility-and-i18n.md +28 -0
- package/expertise/i18n/advanced/bidirectional-text-algorithm.md +38 -0
- package/expertise/i18n/advanced/complex-scripts.md +30 -0
- package/expertise/i18n/advanced/performance-and-i18n.md +27 -0
- package/expertise/i18n/advanced/testing-i18n.md +28 -0
- package/expertise/i18n/content/content-adaptation.md +23 -0
- package/expertise/i18n/content/locale-specific-formatting.md +23 -0
- package/expertise/i18n/content/machine-translation-integration.md +28 -0
- package/expertise/i18n/content/translation-management.md +29 -0
- package/expertise/i18n/foundations/date-time-calendars.md +67 -0
- package/expertise/i18n/foundations/i18n-architecture.md +272 -0
- package/expertise/i18n/foundations/locale-and-language-tags.md +79 -0
- package/expertise/i18n/foundations/numbers-currency-units.md +61 -0
- package/expertise/i18n/foundations/pluralization-and-gender.md +109 -0
- package/expertise/i18n/foundations/string-externalization.md +236 -0
- package/expertise/i18n/foundations/text-direction-bidi.md +241 -0
- package/expertise/i18n/foundations/unicode-and-encoding.md +86 -0
- package/expertise/i18n/index.md +38 -0
- package/expertise/i18n/platform/backend-i18n.md +31 -0
- package/expertise/i18n/platform/flutter-i18n.md +148 -0
- package/expertise/i18n/platform/native-android-i18n.md +36 -0
- package/expertise/i18n/platform/native-ios-i18n.md +36 -0
- package/expertise/i18n/platform/react-i18n.md +103 -0
- package/expertise/i18n/platform/web-css-i18n.md +81 -0
- package/expertise/i18n/rtl/arabic-specific.md +175 -0
- package/expertise/i18n/rtl/hebrew-specific.md +149 -0
- package/expertise/i18n/rtl/rtl-animations-and-transitions.md +111 -0
- package/expertise/i18n/rtl/rtl-forms-and-input.md +161 -0
- package/expertise/i18n/rtl/rtl-fundamentals.md +211 -0
- package/expertise/i18n/rtl/rtl-icons-and-images.md +181 -0
- package/expertise/i18n/rtl/rtl-layout-mirroring.md +252 -0
- package/expertise/i18n/rtl/rtl-navigation-and-gestures.md +107 -0
- package/expertise/i18n/rtl/rtl-testing-and-qa.md +147 -0
- package/expertise/i18n/rtl/rtl-typography.md +160 -0
- package/expertise/index.md +113 -0
- package/expertise/index.yaml +216 -0
- package/expertise/infrastructure/cloud-aws.md +597 -0
- package/expertise/infrastructure/cloud-gcp.md +599 -0
- package/expertise/infrastructure/cybersecurity.md +816 -0
- package/expertise/infrastructure/database-mongodb.md +447 -0
- package/expertise/infrastructure/database-postgres.md +400 -0
- package/expertise/infrastructure/devops-cicd.md +787 -0
- package/expertise/infrastructure/index.md +27 -0
- package/expertise/performance/PROGRESS.md +50 -0
- package/expertise/performance/backend/api-latency.md +1204 -0
- package/expertise/performance/backend/background-jobs.md +506 -0
- package/expertise/performance/backend/connection-pooling.md +1209 -0
- package/expertise/performance/backend/database-query-optimization.md +515 -0
- package/expertise/performance/backend/index.md +23 -0
- package/expertise/performance/backend/rate-limiting-and-throttling.md +971 -0
- package/expertise/performance/foundations/algorithmic-complexity.md +954 -0
- package/expertise/performance/foundations/caching-strategies.md +489 -0
- package/expertise/performance/foundations/concurrency-and-parallelism.md +847 -0
- package/expertise/performance/foundations/index.md +24 -0
- package/expertise/performance/foundations/measuring-and-profiling.md +440 -0
- package/expertise/performance/foundations/memory-management.md +964 -0
- package/expertise/performance/foundations/performance-budgets.md +1314 -0
- package/expertise/performance/index.md +31 -0
- package/expertise/performance/infrastructure/auto-scaling.md +1059 -0
- package/expertise/performance/infrastructure/cdn-and-edge.md +1081 -0
- package/expertise/performance/infrastructure/index.md +22 -0
- package/expertise/performance/infrastructure/load-balancing.md +1081 -0
- package/expertise/performance/infrastructure/observability.md +1079 -0
- package/expertise/performance/mobile/index.md +23 -0
- package/expertise/performance/mobile/mobile-animations.md +544 -0
- package/expertise/performance/mobile/mobile-memory-battery.md +416 -0
- package/expertise/performance/mobile/mobile-network.md +452 -0
- package/expertise/performance/mobile/mobile-rendering.md +599 -0
- package/expertise/performance/mobile/mobile-startup-time.md +505 -0
- package/expertise/performance/platform-specific/flutter-performance.md +647 -0
- package/expertise/performance/platform-specific/index.md +22 -0
- package/expertise/performance/platform-specific/node-performance.md +1307 -0
- package/expertise/performance/platform-specific/postgres-performance.md +1366 -0
- package/expertise/performance/platform-specific/react-performance.md +1403 -0
- package/expertise/performance/web/bundle-optimization.md +1239 -0
- package/expertise/performance/web/image-and-media.md +636 -0
- package/expertise/performance/web/index.md +24 -0
- package/expertise/performance/web/network-optimization.md +1133 -0
- package/expertise/performance/web/rendering-performance.md +1098 -0
- package/expertise/performance/web/ssr-and-hydration.md +918 -0
- package/expertise/performance/web/web-vitals.md +1374 -0
- package/expertise/quality/accessibility.md +985 -0
- package/expertise/quality/evidence-based-verification.md +499 -0
- package/expertise/quality/index.md +24 -0
- package/expertise/quality/ml-model-audit.md +614 -0
- package/expertise/quality/performance.md +600 -0
- package/expertise/quality/testing-api.md +891 -0
- package/expertise/quality/testing-mobile.md +496 -0
- package/expertise/quality/testing-web.md +849 -0
- package/expertise/security/PROGRESS.md +54 -0
- package/expertise/security/agentic-identity.md +540 -0
- package/expertise/security/compliance-frameworks.md +601 -0
- package/expertise/security/data/data-encryption.md +364 -0
- package/expertise/security/data/data-privacy-gdpr.md +692 -0
- package/expertise/security/data/database-security.md +1171 -0
- package/expertise/security/data/index.md +22 -0
- package/expertise/security/data/pii-handling.md +531 -0
- package/expertise/security/foundations/authentication.md +1041 -0
- package/expertise/security/foundations/authorization.md +603 -0
- package/expertise/security/foundations/cryptography.md +1001 -0
- package/expertise/security/foundations/index.md +25 -0
- package/expertise/security/foundations/owasp-top-10.md +1354 -0
- package/expertise/security/foundations/secrets-management.md +1217 -0
- package/expertise/security/foundations/secure-sdlc.md +700 -0
- package/expertise/security/foundations/supply-chain-security.md +698 -0
- package/expertise/security/index.md +31 -0
- package/expertise/security/infrastructure/cloud-security-aws.md +1296 -0
- package/expertise/security/infrastructure/cloud-security-gcp.md +1376 -0
- package/expertise/security/infrastructure/container-security.md +721 -0
- package/expertise/security/infrastructure/incident-response.md +1295 -0
- package/expertise/security/infrastructure/index.md +24 -0
- package/expertise/security/infrastructure/logging-and-monitoring.md +1618 -0
- package/expertise/security/infrastructure/network-security.md +1337 -0
- package/expertise/security/mobile/index.md +23 -0
- package/expertise/security/mobile/mobile-android-security.md +1218 -0
- package/expertise/security/mobile/mobile-binary-protection.md +1229 -0
- package/expertise/security/mobile/mobile-data-storage.md +1265 -0
- package/expertise/security/mobile/mobile-ios-security.md +1401 -0
- package/expertise/security/mobile/mobile-network-security.md +1520 -0
- package/expertise/security/smart-contract-security.md +594 -0
- package/expertise/security/testing/index.md +22 -0
- package/expertise/security/testing/penetration-testing.md +1258 -0
- package/expertise/security/testing/security-code-review.md +1765 -0
- package/expertise/security/testing/threat-modeling.md +1074 -0
- package/expertise/security/testing/vulnerability-scanning.md +1062 -0
- package/expertise/security/web/api-security.md +586 -0
- package/expertise/security/web/cors-and-headers.md +433 -0
- package/expertise/security/web/csrf.md +562 -0
- package/expertise/security/web/file-upload.md +1477 -0
- package/expertise/security/web/index.md +25 -0
- package/expertise/security/web/injection.md +1375 -0
- package/expertise/security/web/session-management.md +1101 -0
- package/expertise/security/web/xss.md +1158 -0
- package/exports/README.md +17 -0
- package/exports/hosts/claude/.claude/agents/clarifier.md +42 -0
- package/exports/hosts/claude/.claude/agents/content-author.md +63 -0
- package/exports/hosts/claude/.claude/agents/designer.md +55 -0
- package/exports/hosts/claude/.claude/agents/executor.md +55 -0
- package/exports/hosts/claude/.claude/agents/learner.md +51 -0
- package/exports/hosts/claude/.claude/agents/planner.md +53 -0
- package/exports/hosts/claude/.claude/agents/researcher.md +43 -0
- package/exports/hosts/claude/.claude/agents/reviewer.md +54 -0
- package/exports/hosts/claude/.claude/agents/specifier.md +47 -0
- package/exports/hosts/claude/.claude/agents/verifier.md +71 -0
- package/exports/hosts/claude/.claude/commands/author.md +42 -0
- package/exports/hosts/claude/.claude/commands/clarify.md +38 -0
- package/exports/hosts/claude/.claude/commands/design-review.md +46 -0
- package/exports/hosts/claude/.claude/commands/design.md +44 -0
- package/exports/hosts/claude/.claude/commands/discover.md +37 -0
- package/exports/hosts/claude/.claude/commands/execute.md +48 -0
- package/exports/hosts/claude/.claude/commands/learn.md +38 -0
- package/exports/hosts/claude/.claude/commands/plan-review.md +42 -0
- package/exports/hosts/claude/.claude/commands/plan.md +39 -0
- package/exports/hosts/claude/.claude/commands/prepare-next.md +37 -0
- package/exports/hosts/claude/.claude/commands/review.md +40 -0
- package/exports/hosts/claude/.claude/commands/run-audit.md +41 -0
- package/exports/hosts/claude/.claude/commands/spec-challenge.md +41 -0
- package/exports/hosts/claude/.claude/commands/specify.md +38 -0
- package/exports/hosts/claude/.claude/commands/verify.md +37 -0
- package/exports/hosts/claude/.claude/settings.json +34 -0
- package/exports/hosts/claude/CLAUDE.md +19 -0
- package/exports/hosts/claude/export.manifest.json +38 -0
- package/exports/hosts/claude/host-package.json +67 -0
- package/exports/hosts/codex/AGENTS.md +19 -0
- package/exports/hosts/codex/export.manifest.json +38 -0
- package/exports/hosts/codex/host-package.json +41 -0
- package/exports/hosts/cursor/.cursor/hooks.json +16 -0
- package/exports/hosts/cursor/.cursor/rules/wazir-core.mdc +19 -0
- package/exports/hosts/cursor/export.manifest.json +38 -0
- package/exports/hosts/cursor/host-package.json +42 -0
- package/exports/hosts/gemini/GEMINI.md +19 -0
- package/exports/hosts/gemini/export.manifest.json +38 -0
- package/exports/hosts/gemini/host-package.json +41 -0
- package/hooks/README.md +18 -0
- package/hooks/definitions/loop_cap_guard.yaml +21 -0
- package/hooks/definitions/post_tool_capture.yaml +24 -0
- package/hooks/definitions/pre_compact_summary.yaml +19 -0
- package/hooks/definitions/pre_tool_capture_route.yaml +19 -0
- package/hooks/definitions/protected_path_write_guard.yaml +19 -0
- package/hooks/definitions/session_start.yaml +19 -0
- package/hooks/definitions/stop_handoff_harvest.yaml +20 -0
- package/hooks/loop-cap-guard +17 -0
- package/hooks/post-tool-lint +36 -0
- package/hooks/protected-path-write-guard +17 -0
- package/hooks/session-start +41 -0
- package/llms-full.txt +2355 -0
- package/llms.txt +43 -0
- package/package.json +79 -0
- package/roles/README.md +20 -0
- package/roles/clarifier.md +42 -0
- package/roles/content-author.md +63 -0
- package/roles/designer.md +55 -0
- package/roles/executor.md +55 -0
- package/roles/learner.md +51 -0
- package/roles/planner.md +53 -0
- package/roles/researcher.md +43 -0
- package/roles/reviewer.md +54 -0
- package/roles/specifier.md +47 -0
- package/roles/verifier.md +71 -0
- package/schemas/README.md +24 -0
- package/schemas/accepted-learning.schema.json +20 -0
- package/schemas/author-artifact.schema.json +156 -0
- package/schemas/clarification.schema.json +19 -0
- package/schemas/design-artifact.schema.json +80 -0
- package/schemas/docs-claim.schema.json +18 -0
- package/schemas/export-manifest.schema.json +20 -0
- package/schemas/hook.schema.json +67 -0
- package/schemas/host-export-package.schema.json +18 -0
- package/schemas/implementation-plan.schema.json +19 -0
- package/schemas/proposed-learning.schema.json +19 -0
- package/schemas/research.schema.json +18 -0
- package/schemas/review.schema.json +29 -0
- package/schemas/run-manifest.schema.json +18 -0
- package/schemas/spec-challenge.schema.json +18 -0
- package/schemas/spec.schema.json +20 -0
- package/schemas/usage.schema.json +102 -0
- package/schemas/verification-proof.schema.json +29 -0
- package/schemas/wazir-manifest.schema.json +173 -0
- package/skills/README.md +40 -0
- package/skills/brainstorming/SKILL.md +77 -0
- package/skills/debugging/SKILL.md +50 -0
- package/skills/design/SKILL.md +61 -0
- package/skills/dispatching-parallel-agents/SKILL.md +128 -0
- package/skills/executing-plans/SKILL.md +70 -0
- package/skills/finishing-a-development-branch/SKILL.md +169 -0
- package/skills/humanize/SKILL.md +123 -0
- package/skills/init-pipeline/SKILL.md +124 -0
- package/skills/prepare-next/SKILL.md +20 -0
- package/skills/receiving-code-review/SKILL.md +123 -0
- package/skills/requesting-code-review/SKILL.md +105 -0
- package/skills/requesting-code-review/code-reviewer.md +108 -0
- package/skills/run-audit/SKILL.md +197 -0
- package/skills/scan-project/SKILL.md +41 -0
- package/skills/self-audit/SKILL.md +153 -0
- package/skills/subagent-driven-development/SKILL.md +154 -0
- package/skills/subagent-driven-development/code-quality-reviewer-prompt.md +26 -0
- package/skills/subagent-driven-development/implementer-prompt.md +102 -0
- package/skills/subagent-driven-development/spec-reviewer-prompt.md +61 -0
- package/skills/tdd/SKILL.md +23 -0
- package/skills/using-git-worktrees/SKILL.md +163 -0
- package/skills/using-skills/SKILL.md +95 -0
- package/skills/verification/SKILL.md +22 -0
- package/skills/wazir/SKILL.md +463 -0
- package/skills/writing-plans/SKILL.md +30 -0
- package/skills/writing-skills/SKILL.md +157 -0
- package/skills/writing-skills/anthropic-best-practices.md +122 -0
- package/skills/writing-skills/persuasion-principles.md +50 -0
- package/templates/README.md +20 -0
- package/templates/artifacts/README.md +10 -0
- package/templates/artifacts/accepted-learning.md +19 -0
- package/templates/artifacts/accepted-learning.template.json +12 -0
- package/templates/artifacts/author.md +74 -0
- package/templates/artifacts/author.template.json +19 -0
- package/templates/artifacts/clarification.md +21 -0
- package/templates/artifacts/clarification.template.json +12 -0
- package/templates/artifacts/execute-notes.md +19 -0
- package/templates/artifacts/implementation-plan.md +21 -0
- package/templates/artifacts/implementation-plan.template.json +11 -0
- package/templates/artifacts/learning-proposal.md +19 -0
- package/templates/artifacts/next-run-handoff.md +21 -0
- package/templates/artifacts/plan-review.md +19 -0
- package/templates/artifacts/proposed-learning.template.json +12 -0
- package/templates/artifacts/research.md +21 -0
- package/templates/artifacts/research.template.json +12 -0
- package/templates/artifacts/review-findings.md +19 -0
- package/templates/artifacts/review.template.json +11 -0
- package/templates/artifacts/run-manifest.template.json +8 -0
- package/templates/artifacts/spec-challenge.md +19 -0
- package/templates/artifacts/spec-challenge.template.json +11 -0
- package/templates/artifacts/spec.md +21 -0
- package/templates/artifacts/spec.template.json +12 -0
- package/templates/artifacts/verification-proof.md +19 -0
- package/templates/artifacts/verification-proof.template.json +11 -0
- package/templates/examples/accepted-learning.example.json +14 -0
- package/templates/examples/author.example.json +152 -0
- package/templates/examples/clarification.example.json +15 -0
- package/templates/examples/docs-claim.example.json +8 -0
- package/templates/examples/export-manifest.example.json +7 -0
- package/templates/examples/host-export-package.example.json +11 -0
- package/templates/examples/implementation-plan.example.json +17 -0
- package/templates/examples/proposed-learning.example.json +13 -0
- package/templates/examples/research.example.json +15 -0
- package/templates/examples/research.example.md +6 -0
- package/templates/examples/review.example.json +17 -0
- package/templates/examples/run-manifest.example.json +9 -0
- package/templates/examples/spec-challenge.example.json +14 -0
- package/templates/examples/spec.example.json +21 -0
- package/templates/examples/verification-proof.example.json +21 -0
- package/templates/examples/wazir-manifest.example.yaml +65 -0
- package/templates/task-definition-schema.md +99 -0
- package/tooling/README.md +20 -0
- package/tooling/src/adapters/context-mode.js +50 -0
- package/tooling/src/capture/command.js +376 -0
- package/tooling/src/capture/store.js +99 -0
- package/tooling/src/capture/usage.js +270 -0
- package/tooling/src/checks/branches.js +50 -0
- package/tooling/src/checks/brand-truth.js +110 -0
- package/tooling/src/checks/changelog.js +231 -0
- package/tooling/src/checks/command-registry.js +36 -0
- package/tooling/src/checks/commits.js +102 -0
- package/tooling/src/checks/docs-drift.js +103 -0
- package/tooling/src/checks/docs-truth.js +201 -0
- package/tooling/src/checks/runtime-surface.js +156 -0
- package/tooling/src/cli.js +116 -0
- package/tooling/src/command-options.js +56 -0
- package/tooling/src/commands/validate.js +320 -0
- package/tooling/src/doctor/command.js +91 -0
- package/tooling/src/export/command.js +77 -0
- package/tooling/src/export/compiler.js +498 -0
- package/tooling/src/guards/loop-cap-guard.js +52 -0
- package/tooling/src/guards/protected-path-write-guard.js +67 -0
- package/tooling/src/index/command.js +152 -0
- package/tooling/src/index/storage.js +1061 -0
- package/tooling/src/index/summarizers.js +261 -0
- package/tooling/src/loaders.js +18 -0
- package/tooling/src/project-root.js +22 -0
- package/tooling/src/recall/command.js +225 -0
- package/tooling/src/schema-validator.js +30 -0
- package/tooling/src/state-root.js +40 -0
- package/tooling/src/status/command.js +71 -0
- package/wazir.manifest.yaml +135 -0
- package/workflows/README.md +19 -0
- package/workflows/author.md +42 -0
- package/workflows/clarify.md +38 -0
- package/workflows/design-review.md +46 -0
- package/workflows/design.md +44 -0
- package/workflows/discover.md +37 -0
- package/workflows/execute.md +48 -0
- package/workflows/learn.md +38 -0
- package/workflows/plan-review.md +42 -0
- package/workflows/plan.md +39 -0
- package/workflows/prepare-next.md +37 -0
- package/workflows/review.md +40 -0
- package/workflows/run-audit.md +41 -0
- package/workflows/spec-challenge.md +41 -0
- package/workflows/specify.md +38 -0
- package/workflows/verify.md +37 -0
|
@@ -0,0 +1,800 @@
|
|
|
1
|
+
# Information Architecture (IA) — Expertise Module
|
|
2
|
+
|
|
3
|
+
> Information architecture is the practice of structuring, organizing, labeling, and designing navigation and search systems so that people can find and understand information effectively. IA sits at the intersection of user mental models, content strategy, and interaction design. It determines whether users succeed or fail at locating information and completing tasks. The discipline draws on library science, cognitive psychology, and systems thinking to create structures that feel intuitive, scale gracefully, and support both human wayfinding and machine discoverability.
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## 1. What This Discipline Covers
|
|
8
|
+
|
|
9
|
+
Information architecture encompasses four interdependent systems, as defined by Rosenfeld, Morville, and Arango in *Information Architecture: For the Web and Beyond* (4th edition):
|
|
10
|
+
|
|
11
|
+
### 1.1 Organization Systems
|
|
12
|
+
|
|
13
|
+
Organization systems determine how content is grouped, categorized, and structured. They answer the question: "How do we classify this information?"
|
|
14
|
+
|
|
15
|
+
**Exact Organization Schemes** — unambiguous, mutually exclusive categories:
|
|
16
|
+
- Alphabetical — dictionary, directory, or glossary ordering
|
|
17
|
+
- Chronological — timelines, archives, event sequences
|
|
18
|
+
- Geographical — location-based grouping (maps, regional content)
|
|
19
|
+
|
|
20
|
+
**Ambiguous Organization Schemes** — require intellectual interpretation, harder to design but often more useful:
|
|
21
|
+
- Topical — by subject matter (most common scheme for content-heavy sites)
|
|
22
|
+
- Task-oriented — organized around what users want to do (e.g., "Pay a bill," "Track an order")
|
|
23
|
+
- Audience-specific — segmented by user type (e.g., "For Students," "For Faculty," "For Alumni")
|
|
24
|
+
- Metaphor-driven — using a familiar concept to explain an unfamiliar structure (use sparingly; metaphors break down)
|
|
25
|
+
- Hybrid — combining multiple schemes (common in practice; requires careful execution to avoid confusion)
|
|
26
|
+
|
|
27
|
+
**Organization Structures** define relationships between content groups:
|
|
28
|
+
- Hierarchy (taxonomy) — top-down tree structure; the backbone of most IAs
|
|
29
|
+
- Heterarchy (database model) — flat, metadata-driven; items belong to multiple categories
|
|
30
|
+
- Hypertext — associative linking; supports non-linear exploration
|
|
31
|
+
- Sequential — linear progression (wizards, tutorials, onboarding flows)
|
|
32
|
+
- Polyhierarchy — items legitimately live in multiple locations in the hierarchy (NNG recommends this for items users expect in more than one place, but warns against overuse)
|
|
33
|
+
|
|
34
|
+
### 1.2 Labeling Systems
|
|
35
|
+
|
|
36
|
+
Labels are the words and phrases used to represent categories, links, headings, and options. Poor labeling is one of the most common IA failures.
|
|
37
|
+
|
|
38
|
+
**Types of labels:**
|
|
39
|
+
- Contextual links — hyperlinked text within content ("Learn more about pricing")
|
|
40
|
+
- Headings — section and page titles that establish hierarchy
|
|
41
|
+
- Navigation labels — menu items that represent categories or destinations
|
|
42
|
+
- Index terms — keywords, tags, and metadata used for search and filtering
|
|
43
|
+
|
|
44
|
+
**Labeling principles:**
|
|
45
|
+
- Use language your users use, not internal jargon or departmental terminology
|
|
46
|
+
- Be consistent — if one section says "Help," do not label the equivalent elsewhere as "Support," "FAQ," and "Resources"
|
|
47
|
+
- Be specific — "Services" is vague; "Cloud Hosting Plans" is actionable
|
|
48
|
+
- Front-load labels with the most meaningful word (users scan the first 2-3 words)
|
|
49
|
+
- Test labels with real users via tree testing and first-click studies
|
|
50
|
+
|
|
51
|
+
### 1.3 Navigation Systems
|
|
52
|
+
|
|
53
|
+
Navigation systems help users move through information space, understand where they are, and know what is available.
|
|
54
|
+
|
|
55
|
+
**Embedded Navigation (integrated into pages):**
|
|
56
|
+
|
|
57
|
+
| System | Purpose | Typical Implementation |
|
|
58
|
+
|--------|---------|----------------------|
|
|
59
|
+
| Global navigation | Persistent site-wide access to top-level sections | Top nav bar, hamburger menu |
|
|
60
|
+
| Local navigation | Section-specific navigation within a subsection | Sidebar, section tabs |
|
|
61
|
+
| Contextual navigation | In-content links to related items | "Related articles," inline links |
|
|
62
|
+
| Breadcrumbs | Show current position in hierarchy | Location-based trail (Home > Category > Page) |
|
|
63
|
+
|
|
64
|
+
**Supplemental Navigation (exist outside page content):**
|
|
65
|
+
|
|
66
|
+
| System | Purpose | Typical Implementation |
|
|
67
|
+
|--------|---------|----------------------|
|
|
68
|
+
| Site map | Complete overview of site structure | HTML page listing all sections |
|
|
69
|
+
| Site index | Alphabetical listing of topics | A-Z index page |
|
|
70
|
+
| Guides/wizards | Task-oriented sequential navigation | Step-by-step flows |
|
|
71
|
+
| Faceted navigation | Multi-dimensional filtering | Filter panels on search/browse pages |
|
|
72
|
+
| Footer navigation | Secondary access to key pages | Fat footer with categorized links |
|
|
73
|
+
| Utility navigation | Access to account, settings, help | Top-right corner links |
|
|
74
|
+
|
|
75
|
+
**Navigation design principles (per Rosenfeld/Morville):**
|
|
76
|
+
- Provide context — users must know where they are, where they have been, and where they can go
|
|
77
|
+
- Maintain consistency — global navigation should not change structure or position across pages
|
|
78
|
+
- Support multiple pathways — different users find information differently; offer hierarchy, search, and cross-links
|
|
79
|
+
- Offer escape hatches — users should always be able to get back to known ground (home, up one level)
|
|
80
|
+
- Limit choices per level — Miller's Law suggests 7 plus or minus 2 items; in practice, 5-9 primary navigation items perform best
|
|
81
|
+
|
|
82
|
+
### 1.4 Search Systems
|
|
83
|
+
|
|
84
|
+
Search systems complement navigation for large or complex information spaces. IA governs what is searchable, how results are organized, and what refinement is available.
|
|
85
|
+
|
|
86
|
+
**Search system components:**
|
|
87
|
+
- Search interface — input field, auto-suggest, advanced search options
|
|
88
|
+
- Search engine/algorithm — indexing, relevance ranking, weighting
|
|
89
|
+
- Search results — display format, snippets, metadata, pagination
|
|
90
|
+
- Search refinement — filters, facets, sorting, "did you mean" corrections
|
|
91
|
+
- Search zones — ability to scope search to a section, content type, or date range
|
|
92
|
+
|
|
93
|
+
**When search is critical:**
|
|
94
|
+
- Sites with more than 100-200 content items
|
|
95
|
+
- Users who arrive with a specific known-item need
|
|
96
|
+
- Content that does not fit neatly into a single hierarchical path
|
|
97
|
+
- E-commerce, documentation, knowledge bases, intranets
|
|
98
|
+
|
|
99
|
+
**Search strategy decisions:**
|
|
100
|
+
- What content gets indexed (and what gets excluded)
|
|
101
|
+
- How synonyms and related terms are handled (controlled vocabulary, thesaurus)
|
|
102
|
+
- What metadata is surfaced in results (dates, authors, content types)
|
|
103
|
+
- How "no results" states are handled (suggestions, popular content, help)
|
|
104
|
+
- Whether federated search across multiple repositories is needed
|
|
105
|
+
|
|
106
|
+
---
|
|
107
|
+
|
|
108
|
+
## 2. Core Methods & Frameworks
|
|
109
|
+
|
|
110
|
+
### 2.1 Card Sorting
|
|
111
|
+
|
|
112
|
+
Card sorting reveals how users naturally group and categorize information. It is the primary generative method for discovering user mental models.
|
|
113
|
+
|
|
114
|
+
**Open Card Sort:**
|
|
115
|
+
- Participants receive 30-60 content items on individual cards
|
|
116
|
+
- They create their own groups and name the categories
|
|
117
|
+
- Best for: early-stage IA design, discovering user mental models, generating category ideas
|
|
118
|
+
- Sample size: 15-30 participants yields reliable patterns (NNG)
|
|
119
|
+
- Analysis: similarity matrix, dendrogram (cluster analysis), category frequency
|
|
120
|
+
|
|
121
|
+
**Closed Card Sort:**
|
|
122
|
+
- Participants sort cards into predefined categories
|
|
123
|
+
- Best for: validating an existing or proposed IA structure
|
|
124
|
+
- Reveals: which categories are clear, which are confusing, where items lack a natural home
|
|
125
|
+
- Sample size: 15-30 participants
|
|
126
|
+
|
|
127
|
+
**Hybrid Card Sort:**
|
|
128
|
+
- Participants sort into predefined categories but can also create new ones
|
|
129
|
+
- Best for: refining a draft IA — validates what works while revealing gaps
|
|
130
|
+
- Combines generative and evaluative insights
|
|
131
|
+
|
|
132
|
+
**Card sorting best practices (per NNG and Optimal Workshop):**
|
|
133
|
+
- Write card labels using language from actual content (page titles, feature names)
|
|
134
|
+
- Avoid cards with overlapping keywords — users cluster by shared words, not meaning
|
|
135
|
+
- Include 30-70 cards; fewer than 20 provides insufficient data, more than 70 causes fatigue
|
|
136
|
+
- Capture think-aloud data in moderated sessions for qualitative insight
|
|
137
|
+
- Run remote unmoderated sorts for larger sample sizes
|
|
138
|
+
- Analyze with both quantitative (similarity matrices) and qualitative (participant comments) methods
|
|
139
|
+
- Do not treat results as prescriptive — card sorting informs IA decisions, it does not make them
|
|
140
|
+
|
|
141
|
+
### 2.2 Tree Testing
|
|
142
|
+
|
|
143
|
+
Tree testing (also called "reverse card sorting") evaluates an existing or proposed IA by asking users to find items in a text-only hierarchy — no visual design, no navigation aids.
|
|
144
|
+
|
|
145
|
+
**Process:**
|
|
146
|
+
1. Create a text-based tree representing your IA hierarchy
|
|
147
|
+
2. Write 8-10 task scenarios ("Where would you find information about returning a product?")
|
|
148
|
+
3. Participants navigate the tree to find the correct location
|
|
149
|
+
4. Measure: success rate, directness (found it without backtracking), time to complete
|
|
150
|
+
|
|
151
|
+
**Key metrics:**
|
|
152
|
+
- Task success rate — percentage of participants who found the correct answer
|
|
153
|
+
- Directness — percentage who navigated directly without backtracking (indicates confidence)
|
|
154
|
+
- Time on task — longer times suggest labeling or structure confusion
|
|
155
|
+
- First click correctness — if the first click is correct, overall success rate is significantly higher
|
|
156
|
+
|
|
157
|
+
**Tree testing best practices:**
|
|
158
|
+
- Test with 50+ participants for statistically reliable results
|
|
159
|
+
- Keep sessions under 15-20 minutes (fewer than 10 tasks)
|
|
160
|
+
- Randomize task order to eliminate learning effects
|
|
161
|
+
- Test competitor or alternative structures for comparison
|
|
162
|
+
- Run tree testing after card sorting to validate the IA generated from card sort insights
|
|
163
|
+
|
|
164
|
+
**Combined workflow (recommended by NNG):**
|
|
165
|
+
1. Open card sort to discover mental models
|
|
166
|
+
2. Draft IA structure from card sort results
|
|
167
|
+
3. Tree test the draft IA to evaluate findability
|
|
168
|
+
4. Iterate on labels and structure based on results
|
|
169
|
+
5. Re-test until success rates meet targets (aim for 80%+ task success)
|
|
170
|
+
|
|
171
|
+
### 2.3 Site Maps
|
|
172
|
+
|
|
173
|
+
A site map is a visual representation of the IA hierarchy showing all pages, sections, and their relationships.
|
|
174
|
+
|
|
175
|
+
**Types:**
|
|
176
|
+
- Hierarchical site map — tree diagram showing parent-child relationships
|
|
177
|
+
- Flat site map — list format, often used for XML sitemaps (SEO)
|
|
178
|
+
- Visual site map — diagrammatic with annotations for page types, templates, and content models
|
|
179
|
+
|
|
180
|
+
**Creating effective site maps:**
|
|
181
|
+
- Start from the top level and work down; limit depth to 3-4 levels where possible
|
|
182
|
+
- Use consistent visual conventions (boxes for pages, lines for relationships, color for page types)
|
|
183
|
+
- Annotate with page templates, content types, and dynamic behavior
|
|
184
|
+
- Include cross-links and polyhierarchy where items appear in multiple locations
|
|
185
|
+
- Version and date site maps — they are living documents that evolve with the product
|
|
186
|
+
|
|
187
|
+
### 2.4 User Flows
|
|
188
|
+
|
|
189
|
+
User flows map the paths users take to accomplish specific tasks through the information architecture.
|
|
190
|
+
|
|
191
|
+
**Components:**
|
|
192
|
+
- Entry points — where users begin (homepage, search engine, deep link, notification)
|
|
193
|
+
- Decision points — where users make choices (navigation clicks, search queries, filter selections)
|
|
194
|
+
- Pages/screens — the content they encounter along the way
|
|
195
|
+
- Exit points — task completion, abandonment, or redirection
|
|
196
|
+
|
|
197
|
+
**User flow best practices:**
|
|
198
|
+
- Map flows for the top 5-10 critical user tasks
|
|
199
|
+
- Include both the "happy path" and common alternative paths
|
|
200
|
+
- Identify dead ends, loops, and unnecessary steps
|
|
201
|
+
- Validate flows against analytics data (actual user behavior vs. intended paths)
|
|
202
|
+
- Use flows to identify where the IA creates friction or forces unnecessary navigation
|
|
203
|
+
|
|
204
|
+
### 2.5 Content Inventory and Audit
|
|
205
|
+
|
|
206
|
+
A content inventory catalogs every piece of content in an existing system. A content audit evaluates the quality, accuracy, and relevance of that content.
|
|
207
|
+
|
|
208
|
+
**Content Inventory — what to capture per item:**
|
|
209
|
+
URL/location, page title, content type, owner/author, last updated date, word count, metadata (tags/categories/keywords), traffic/usage data, status (active/outdated/duplicate/orphaned), and current IA location.
|
|
210
|
+
|
|
211
|
+
**Content Audit — evaluation criteria:**
|
|
212
|
+
- Accuracy — is the information still correct?
|
|
213
|
+
- Relevance — does the audience still need this content?
|
|
214
|
+
- Completeness — are there gaps in coverage?
|
|
215
|
+
- Consistency — does it follow current style, tone, and terminology?
|
|
216
|
+
- Findability — can users reach this content through navigation and search?
|
|
217
|
+
- ROT analysis — identify content that is Redundant, Outdated, or Trivial
|
|
218
|
+
|
|
219
|
+
**Conducting the audit:** Export a full inventory via crawler (Screaming Frog, Sitebulb) or CMS export. Enrich with analytics data to identify high-traffic and zero-traffic pages. Categorize by type, topic, audience, and lifecycle stage. Score each item on accuracy, relevance, and quality. Make disposition decisions (keep, update, merge, archive, delete). Use findings to inform the new IA.
|
|
220
|
+
|
|
221
|
+
### 2.6 Mental Model Alignment
|
|
222
|
+
|
|
223
|
+
A mental model is a user's internal representation of how they expect information to be organized. IA succeeds when it matches these expectations; it fails when it imposes structures that conflict with user cognition.
|
|
224
|
+
|
|
225
|
+
**Methods for discovering mental models:**
|
|
226
|
+
- Open card sorting — reveals natural grouping patterns
|
|
227
|
+
- User interviews — ask users to describe how they think about a topic domain
|
|
228
|
+
- Diary studies — observe how users naturally seek and organize information over time
|
|
229
|
+
- Search log analysis — actual queries reveal the language and categories users expect
|
|
230
|
+
- Competitor analysis — observe IA patterns users are already accustomed to
|
|
231
|
+
- Mental model diagrams (per Indi Young) — map user behaviors, thoughts, and feelings to content and features
|
|
232
|
+
|
|
233
|
+
**Alignment strategies:**
|
|
234
|
+
- Match top-level categories to the user's task or topic model, not the organization's departmental structure
|
|
235
|
+
- Use the same vocabulary users use (discovered through research, search logs, and support tickets)
|
|
236
|
+
- Provide multiple pathways when user mental models diverge (some users think by topic, others by task)
|
|
237
|
+
- Use polyhierarchy to place items where multiple mental models expect them
|
|
238
|
+
- Test alignment continuously — mental models shift as users gain expertise and as the product evolves
|
|
239
|
+
|
|
240
|
+
### 2.7 Taxonomies and Controlled Vocabularies
|
|
241
|
+
|
|
242
|
+
Taxonomies provide standardized classification systems. Controlled vocabularies ensure consistent labeling across content, navigation, and search.
|
|
243
|
+
|
|
244
|
+
**Taxonomy types:**
|
|
245
|
+
- Flat taxonomy — a single list of terms with no hierarchy (tags)
|
|
246
|
+
- Hierarchical taxonomy — terms arranged in parent-child relationships (categories > subcategories)
|
|
247
|
+
- Faceted taxonomy — multiple independent dimensions for classifying the same content (topic, format, audience, date)
|
|
248
|
+
- Network taxonomy — terms connected through associative relationships (related terms, see-also references)
|
|
249
|
+
|
|
250
|
+
**Controlled vocabulary components:**
|
|
251
|
+
- Preferred terms — the canonical label for a concept
|
|
252
|
+
- Synonyms/variants — alternative terms that map to the preferred term ("cell phone" maps to "mobile phone")
|
|
253
|
+
- Broader terms (BT) — parent concepts
|
|
254
|
+
- Narrower terms (NT) — child concepts
|
|
255
|
+
- Related terms (RT) — associated concepts that are not hierarchically related
|
|
256
|
+
- Scope notes — definitions clarifying when and how to apply a term
|
|
257
|
+
|
|
258
|
+
**Building a taxonomy:**
|
|
259
|
+
1. Gather existing classification schemes from the CMS, content, and stakeholders
|
|
260
|
+
2. Analyze search logs for user language patterns
|
|
261
|
+
3. Conduct open card sorts to surface user-generated categories
|
|
262
|
+
4. Draft the taxonomy with preferred terms, synonyms, and hierarchy
|
|
263
|
+
5. Validate with subject matter experts (SMEs) for domain accuracy
|
|
264
|
+
6. Test with tree testing and closed card sorts for user comprehension
|
|
265
|
+
7. Document governance rules — who can add, modify, or deprecate terms
|
|
266
|
+
8. Plan for maintenance — taxonomies require ongoing curation as content evolves
|
|
267
|
+
|
|
268
|
+
### 2.8 IA Heuristics
|
|
269
|
+
|
|
270
|
+
Abby Covert synthesized five historical sources of IA evaluation criteria into ten heuristic principles. These provide a structured framework for evaluating any information architecture:
|
|
271
|
+
|
|
272
|
+
**Covert's Ten IA Heuristics:**
|
|
273
|
+
|
|
274
|
+
| Heuristic | Evaluation Question |
|
|
275
|
+
|-----------|-------------------|
|
|
276
|
+
| Findable | Can users locate the information they need? |
|
|
277
|
+
| Accessible | Can all users access the content regardless of ability or device? |
|
|
278
|
+
| Clear | Is the meaning of labels, categories, and structures unambiguous? |
|
|
279
|
+
| Communicative | Does the IA convey the scope, purpose, and structure of the content? |
|
|
280
|
+
| Useful | Does the structure help users accomplish their goals? |
|
|
281
|
+
| Credible | Does the organization of information inspire trust and confidence? |
|
|
282
|
+
| Controllable | Can users navigate, filter, and customize their experience? |
|
|
283
|
+
| Valuable | Does the IA deliver value to both users and the organization? |
|
|
284
|
+
| Learnable | Can users build a mental model of the structure and predict where things are? |
|
|
285
|
+
| Delightful | Does the IA create a pleasant, satisfying experience of finding information? |
|
|
286
|
+
|
|
287
|
+
**Dan Brown's Eight Principles of IA:**
|
|
288
|
+
|
|
289
|
+
| Principle | Description |
|
|
290
|
+
|-----------|-------------|
|
|
291
|
+
| Objects | Treat content as a living thing with a lifecycle, behaviors, and attributes |
|
|
292
|
+
| Choices | Present meaningful choices focused on a particular task; avoid overwhelming users |
|
|
293
|
+
| Disclosure | Reveal just enough information to help users anticipate what they will find next |
|
|
294
|
+
| Exemplars | Show examples of category contents to clarify ambiguous labels |
|
|
295
|
+
| Front Doors | Assume users enter from any page, not just the homepage; every page must provide context |
|
|
296
|
+
| Multiple Classifications | Offer several ways to browse the same content (topic, task, audience) |
|
|
297
|
+
| Focused Navigation | Keep each navigation scheme focused on one organizing principle; do not mix metaphors |
|
|
298
|
+
| Growth | Design the IA to accommodate future content without structural rework |
|
|
299
|
+
|
|
300
|
+
---
|
|
301
|
+
|
|
302
|
+
## 3. Deliverables
|
|
303
|
+
|
|
304
|
+
### 3.1 Site Maps
|
|
305
|
+
|
|
306
|
+
**Description:** Visual diagrams showing the hierarchical structure of all pages, sections, and their relationships.
|
|
307
|
+
|
|
308
|
+
**Quality criteria:**
|
|
309
|
+
- Covers all content areas — no orphaned sections
|
|
310
|
+
- Clearly indicates hierarchy depth (aim for 3-4 levels maximum)
|
|
311
|
+
- Distinguishes page types visually (landing pages, detail pages, utility pages, forms)
|
|
312
|
+
- Annotates dynamic content areas (search results, filtered views, user-generated content)
|
|
313
|
+
- Shows cross-links and polyhierarchy where items appear in multiple locations
|
|
314
|
+
- Includes a legend explaining visual conventions
|
|
315
|
+
- Is versioned and dated for change tracking
|
|
316
|
+
- Has been validated through tree testing with representative users
|
|
317
|
+
|
|
318
|
+
### 3.2 Navigation Structures
|
|
319
|
+
|
|
320
|
+
**Description:** Specifications for all navigation systems — global, local, contextual, supplemental — including labels, hierarchy, and behavior.
|
|
321
|
+
|
|
322
|
+
**Quality criteria:**
|
|
323
|
+
- Global navigation limited to 5-9 top-level items
|
|
324
|
+
- Labels tested with users (via tree testing or preference testing)
|
|
325
|
+
- Responsive behavior specified (how navigation adapts on mobile, tablet, desktop)
|
|
326
|
+
- States defined (default, hover, active, current, disabled)
|
|
327
|
+
- Mega-menu content specified where applicable (groupings, featured items, CTAs)
|
|
328
|
+
- Local navigation defined for each major section
|
|
329
|
+
- Breadcrumb logic documented (what appears at each level)
|
|
330
|
+
- Utility navigation items identified (search, account, language, help)
|
|
331
|
+
|
|
332
|
+
### 3.3 Content Models
|
|
333
|
+
|
|
334
|
+
**Description:** Definitions of content types, their attributes, relationships, and display rules.
|
|
335
|
+
|
|
336
|
+
**Quality criteria:**
|
|
337
|
+
- Every content type has a defined schema (title, body, metadata fields, relationships)
|
|
338
|
+
- Relationships between content types are explicit (article has-many tags, product belongs-to category)
|
|
339
|
+
- Required vs. optional fields are specified
|
|
340
|
+
- Character limits and formatting rules are documented
|
|
341
|
+
- Content lifecycle states are defined (draft, review, published, archived)
|
|
342
|
+
- Reuse patterns are identified (shared components, content blocks, snippets)
|
|
343
|
+
- Model supports the taxonomy and classification scheme
|
|
344
|
+
- Validated against actual content during audit
|
|
345
|
+
|
|
346
|
+
### 3.4 Taxonomies
|
|
347
|
+
|
|
348
|
+
**Description:** The complete classification system with all terms, relationships, synonyms, and governance rules.
|
|
349
|
+
|
|
350
|
+
**Quality criteria:**
|
|
351
|
+
- Terms are user-tested and align with user vocabulary (not internal jargon)
|
|
352
|
+
- Hierarchy depth is manageable (3-4 levels maximum)
|
|
353
|
+
- Each term has a scope note defining its meaning and usage
|
|
354
|
+
- Synonyms and variant terms are mapped to preferred terms
|
|
355
|
+
- Governance process is documented (who adds, modifies, deprecates terms)
|
|
356
|
+
- Taxonomy is faceted where content needs multiple classification dimensions
|
|
357
|
+
- Cross-references (related terms) are defined where helpful
|
|
358
|
+
- Growth plan accounts for new content areas
|
|
359
|
+
|
|
360
|
+
### 3.5 User Flow Diagrams
|
|
361
|
+
|
|
362
|
+
**Description:** Visual maps of the paths users take to accomplish key tasks through the IA.
|
|
363
|
+
|
|
364
|
+
**Quality criteria:**
|
|
365
|
+
- Cover the top 5-10 critical user tasks
|
|
366
|
+
- Include entry points from all major channels (search engine, direct, referral, notification)
|
|
367
|
+
- Show decision points with branching logic
|
|
368
|
+
- Identify error states and recovery paths
|
|
369
|
+
- Mark the "happy path" distinctly from alternative paths
|
|
370
|
+
- Note where analytics data validates or contradicts the intended flow
|
|
371
|
+
- Include estimated completion time and step count
|
|
372
|
+
- Have been validated against usability testing observations
|
|
373
|
+
|
|
374
|
+
### 3.6 Content Inventory Spreadsheet
|
|
375
|
+
|
|
376
|
+
**Description:** Complete catalog of all existing content with metadata and audit scores.
|
|
377
|
+
|
|
378
|
+
**Quality criteria:**
|
|
379
|
+
- Every page/content item is included (no gaps)
|
|
380
|
+
- Metadata fields are consistently populated
|
|
381
|
+
- Audit scores are applied using consistent criteria
|
|
382
|
+
- Disposition recommendations are provided for every item (keep, update, merge, archive, delete)
|
|
383
|
+
- Analytics data (traffic, engagement) is integrated
|
|
384
|
+
- Owner/stakeholder is assigned for each content area
|
|
385
|
+
- Document is maintained as a living artifact through the redesign process
|
|
386
|
+
|
|
387
|
+
---
|
|
388
|
+
|
|
389
|
+
## 4. Tools & Techniques
|
|
390
|
+
|
|
391
|
+
### 4.1 Optimal Workshop — Card Sorting & Tree Testing
|
|
392
|
+
|
|
393
|
+
**OptimalSort (card sorting):**
|
|
394
|
+
- Supports open, closed, and hybrid card sorts
|
|
395
|
+
- Remote unmoderated sessions scale to hundreds of participants
|
|
396
|
+
- Built-in analysis: similarity matrix, dendrogram, participant-centric analysis
|
|
397
|
+
- Standardization grid shows how consistently participants placed each card
|
|
398
|
+
- Export raw data for custom analysis
|
|
399
|
+
|
|
400
|
+
**Treejack (tree testing):**
|
|
401
|
+
- Upload a text-based hierarchy to test findability
|
|
402
|
+
- Measures success rate, directness, and time-on-task per task
|
|
403
|
+
- Pietree visualization shows where users go right and wrong at each node
|
|
404
|
+
- First-click analysis reveals whether users start on the correct path
|
|
405
|
+
- Compare multiple tree structures side by side
|
|
406
|
+
|
|
407
|
+
**Other Optimal Workshop tools relevant to IA:**
|
|
408
|
+
- Chalkmark — first-click testing on wireframes or mockups
|
|
409
|
+
- Reframer — qualitative research analysis and tagging
|
|
410
|
+
- Questions — survey tool integrated with IA research
|
|
411
|
+
|
|
412
|
+
### 4.2 Miro & FigJam — Visual Mapping
|
|
413
|
+
|
|
414
|
+
**Use for:**
|
|
415
|
+
- Collaborative site map creation during workshops
|
|
416
|
+
- Affinity mapping of card sort results
|
|
417
|
+
- User flow diagramming with stakeholder participation
|
|
418
|
+
- Content model visualization
|
|
419
|
+
- IA workshop facilitation (remote and in-person)
|
|
420
|
+
|
|
421
|
+
**Best practices:**
|
|
422
|
+
- Use templates and component libraries for consistent site map notation
|
|
423
|
+
- Color-code by content type, template, or section owner
|
|
424
|
+
- Use frames to organize different IA views (current state vs. proposed)
|
|
425
|
+
- Add sticky notes for annotations, questions, and decisions
|
|
426
|
+
- Export to PDF for stakeholder review and documentation
|
|
427
|
+
|
|
428
|
+
### 4.3 Spreadsheets — Content Inventory
|
|
429
|
+
|
|
430
|
+
**Google Sheets / Excel / Airtable for:**
|
|
431
|
+
- Content inventory and audit tracking
|
|
432
|
+
- Taxonomy management and term definitions
|
|
433
|
+
- Metadata schema documentation
|
|
434
|
+
- URL mapping (old URL to new URL for redirects)
|
|
435
|
+
- Navigation specification tables
|
|
436
|
+
|
|
437
|
+
**Spreadsheet structure for content inventory:**
|
|
438
|
+
```
|
|
439
|
+
| ID | URL | Title | Content Type | Section | Owner | Last Updated | Traffic | Audit Score | Disposition |
|
|
440
|
+
```
|
|
441
|
+
|
|
442
|
+
**Tips:**
|
|
443
|
+
- Use data validation for content type and disposition columns (consistency)
|
|
444
|
+
- Create pivot tables to summarize content by type, section, and disposition
|
|
445
|
+
- Use conditional formatting to highlight outdated or orphaned content
|
|
446
|
+
- Maintain a separate sheet for the taxonomy with term definitions
|
|
447
|
+
- Use Airtable for relational data (linking content items to taxonomy terms, owners, and templates)
|
|
448
|
+
|
|
449
|
+
### 4.4 Diagramming Tools
|
|
450
|
+
|
|
451
|
+
**Draw.io (diagrams.net) / Lucidchart / OmniGraffle:**
|
|
452
|
+
- Formal site map creation with professional notation
|
|
453
|
+
- User flow diagrams with standardized shapes (Jesse James Garrett's visual vocabulary)
|
|
454
|
+
- Content model entity-relationship diagrams
|
|
455
|
+
- Navigation structure specifications
|
|
456
|
+
|
|
457
|
+
**Standard visual vocabulary:** Rectangle (page), diamond (decision point), circle (entry/exit), rounded rectangle (action), dashed line (conditional), solid line (required path). Use color coding for content type, template, or status.
|
|
458
|
+
|
|
459
|
+
### 4.5 Analytics Tools for IA Research
|
|
460
|
+
|
|
461
|
+
**Google Analytics / Matomo / Amplitude** — Use navigation summaries, site search reports (top queries, zero-result queries, query reformulations), behavior flows, and landing/exit page analysis to validate IA against actual user behavior. Search logs are especially valuable: top queries reveal what users expect to find, zero-result queries reveal content or vocabulary gaps, and reformulations indicate labeling confusion.
|
|
462
|
+
|
|
463
|
+
### 4.6 Prototyping for IA Validation
|
|
464
|
+
|
|
465
|
+
**Axure / Figma / Sketch** — Build interactive navigation prototypes for usability testing, click-through site maps for stakeholder review, and responsive navigation behavior validation.
|
|
466
|
+
|
|
467
|
+
---
|
|
468
|
+
|
|
469
|
+
## 5. Common Failures
|
|
470
|
+
|
|
471
|
+
### 5.1 Organizing by Organizational Structure, Not User Mental Models
|
|
472
|
+
|
|
473
|
+
**The problem:** The IA mirrors the company's org chart — "Marketing," "Engineering," "Human Resources" — rather than reflecting how users think about the content. Each department demands its own section in the navigation.
|
|
474
|
+
|
|
475
|
+
**Why it happens:** Internal politics, stakeholder demands, path of least resistance during design.
|
|
476
|
+
|
|
477
|
+
**The fix:**
|
|
478
|
+
- Conduct card sorting with external users to discover their mental models
|
|
479
|
+
- Present user research data to stakeholders as evidence for user-centered structure
|
|
480
|
+
- Map departmental content to user-centered categories (departments own content but do not own navigation labels)
|
|
481
|
+
- Use audience-based or task-based top-level navigation instead of department-based
|
|
482
|
+
|
|
483
|
+
**NNG guidance:** "Clumsy org-chart sites arranged solely by how the organization is managed are much less amusing to users who cannot find what they are looking for because they do not understand — or care — how your management is organized."
|
|
484
|
+
|
|
485
|
+
### 5.2 Hierarchy Too Deep
|
|
486
|
+
|
|
487
|
+
**The problem:** Users must click through 5, 6, or more levels to reach content. Each click increases cognitive load and the risk of abandonment.
|
|
488
|
+
|
|
489
|
+
**Why it happens:** Over-categorization, desire for "neat" structures, failure to consider user patience.
|
|
490
|
+
|
|
491
|
+
**The fix:**
|
|
492
|
+
- Aim for no more than 3-4 levels of depth for most content
|
|
493
|
+
- Prefer wider (more items per level) over deeper (more levels) structures
|
|
494
|
+
- Use cross-links and contextual navigation to provide shortcuts to deep content
|
|
495
|
+
- Implement breadcrumbs to help users recover from deep navigation
|
|
496
|
+
- Use faceted navigation as an alternative to deep hierarchies for filterable content
|
|
497
|
+
- Monitor analytics for drop-off at each navigation level
|
|
498
|
+
|
|
499
|
+
**NNG guidance:** "Requiring users to click through many levels to get to specific content usually does not work well, as users easily become lost, distracted, or simply decide it is too much work and give up."
|
|
500
|
+
|
|
501
|
+
### 5.3 Inconsistent Labeling
|
|
502
|
+
|
|
503
|
+
**The problem:** The same concept is labeled differently across the site — "Help" in the header, "Support" in the footer, "FAQ" on a landing page, "Knowledge Base" in search. Users cannot build a reliable mental model.
|
|
504
|
+
|
|
505
|
+
**Why it happens:** Different teams create content independently, no terminology governance, no labeling standards documented.
|
|
506
|
+
|
|
507
|
+
**The fix:**
|
|
508
|
+
- Create a controlled vocabulary with preferred terms and documented synonyms
|
|
509
|
+
- Audit all navigation labels, page titles, and CTAs for consistency
|
|
510
|
+
- Establish labeling guidelines in the content style guide
|
|
511
|
+
- Assign taxonomy governance to a specific role or team
|
|
512
|
+
- Use search synonyms to handle user vocabulary variations without UI inconsistency
|
|
513
|
+
|
|
514
|
+
### 5.4 No Search Strategy
|
|
515
|
+
|
|
516
|
+
**The problem:** Search is treated as a feature to "just add" rather than a system to design. Results are irrelevant, filters are missing, zero-result pages offer no help, and the search index includes outdated content.
|
|
517
|
+
|
|
518
|
+
**Why it happens:** Search is often considered a technical feature rather than an IA concern. No one owns the search experience end-to-end.
|
|
519
|
+
|
|
520
|
+
**The fix:**
|
|
521
|
+
- Define what gets indexed and what does not (exclude outdated, duplicate, or administrative content)
|
|
522
|
+
- Implement a synonym/thesaurus layer so user vocabulary maps to content vocabulary
|
|
523
|
+
- Design the zero-results state with suggestions, popular content, and help options
|
|
524
|
+
- Add faceted filtering for search results (content type, date, section, topic)
|
|
525
|
+
- Analyze search logs regularly to identify gaps, failed queries, and vocabulary mismatches
|
|
526
|
+
- Treat search as a navigation system that requires the same IA rigor as the main navigation
|
|
527
|
+
|
|
528
|
+
### 5.5 Jargon in Navigation
|
|
529
|
+
|
|
530
|
+
**The problem:** Navigation labels use internal terminology, industry jargon, or product names that users do not understand. "Synergy Solutions" means nothing to a user looking for "Consulting Services."
|
|
531
|
+
|
|
532
|
+
**Why it happens:** Subject matter experts write labels using their own vocabulary. Marketing insists on branded terminology. No user testing of labels.
|
|
533
|
+
|
|
534
|
+
**The fix:**
|
|
535
|
+
- Test all navigation labels with representative users via tree testing
|
|
536
|
+
- Use search log analysis to discover the language users actually use
|
|
537
|
+
- Replace branded or jargon terms with plain language in navigation (use branded terms on landing pages instead)
|
|
538
|
+
- Apply the front-loading principle — put the most meaningful, recognizable word first in every label
|
|
539
|
+
- When domain-specific terms are necessary, provide contextual help (tooltips, descriptions)
|
|
540
|
+
|
|
541
|
+
### 5.6 Flat Swamp — No Organizing Principle
|
|
542
|
+
|
|
543
|
+
**The problem:** Content is treated as a flat collection of individual items with no grouping, hierarchy, or relationship structure. Every page is equally accessible (or inaccessible) from every other page.
|
|
544
|
+
|
|
545
|
+
**Why it happens:** Content grows organically without planning. CMS allows creation without requiring classification. No IA governance.
|
|
546
|
+
|
|
547
|
+
**The fix:**
|
|
548
|
+
- Conduct a content audit to identify themes, types, and natural groupings
|
|
549
|
+
- Build a taxonomy retroactively and apply it to all existing content
|
|
550
|
+
- Create section landing pages that curate and organize related content
|
|
551
|
+
- Implement related-content links based on taxonomy relationships
|
|
552
|
+
- Establish content governance requiring classification at time of creation
|
|
553
|
+
|
|
554
|
+
### 5.7 Neglecting Mobile IA
|
|
555
|
+
|
|
556
|
+
**The problem:** The IA was designed for desktop with 8-10 top-level navigation items, mega-menus, and sidebar navigation. On mobile, it collapses into an unusable hamburger menu with deeply nested levels.
|
|
557
|
+
|
|
558
|
+
**Why it happens:** IA designed before responsive considerations. Desktop-first mindset.
|
|
559
|
+
|
|
560
|
+
**The fix:**
|
|
561
|
+
- Design IA mobile-first — if it works on a small screen, it will work on a large one
|
|
562
|
+
- Prioritize navigation items for mobile (not everything needs to be in the hamburger menu)
|
|
563
|
+
- Use progressive disclosure — show top-level categories first, reveal sub-levels on interaction
|
|
564
|
+
- Consider bottom navigation for the 3-5 most critical sections on mobile
|
|
565
|
+
- Test navigation on actual mobile devices, not just responsive browser simulations
|
|
566
|
+
|
|
567
|
+
### 5.8 Orphaned Content
|
|
568
|
+
|
|
569
|
+
**The problem:** Pages exist in the CMS but are not linked from any navigation, category page, or related-content module. Users cannot find them through browsing; they are only accessible via direct URL or search (if indexed).
|
|
570
|
+
|
|
571
|
+
**Why it happens:** Content is created and published without being placed in the IA. Navigation updates lag behind content creation. Redesigns leave old pages stranded.
|
|
572
|
+
|
|
573
|
+
**The fix:**
|
|
574
|
+
- Run regular crawls to identify orphaned pages (Screaming Frog, Sitebulb)
|
|
575
|
+
- Require content creators to specify IA placement when publishing
|
|
576
|
+
- Include orphaned-page checks in content governance processes
|
|
577
|
+
- Either integrate orphaned content into the IA or remove/redirect it
|
|
578
|
+
|
|
579
|
+
---
|
|
580
|
+
|
|
581
|
+
## 6. Integration with Development
|
|
582
|
+
|
|
583
|
+
### 6.1 URL Structure
|
|
584
|
+
|
|
585
|
+
The IA should directly inform the URL structure. URLs are a user-facing representation of information hierarchy.
|
|
586
|
+
|
|
587
|
+
**Principles:**
|
|
588
|
+
- URLs should reflect the IA hierarchy: `/category/subcategory/item-name`
|
|
589
|
+
- Use human-readable slugs, not IDs or query parameters: `/products/wireless-headphones` not `/products?id=4829`
|
|
590
|
+
- Keep URLs as short as possible while remaining descriptive
|
|
591
|
+
- Use hyphens, not underscores, to separate words (Google treats hyphens as word separators)
|
|
592
|
+
- Maintain URL consistency — changing URLs breaks bookmarks, shared links, and SEO equity
|
|
593
|
+
- Plan a redirect strategy (301 redirects) for any URL changes during IA restructuring
|
|
594
|
+
|
|
595
|
+
**URL structure anti-patterns:**
|
|
596
|
+
- URLs that expose database structure: `/node/12847`
|
|
597
|
+
- URLs that repeat the domain in the path: `/company-name/company-name-products/`
|
|
598
|
+
- Overly deep URLs: `/a/b/c/d/e/f/page.html` (signals IA depth problems)
|
|
599
|
+
- Parameter-heavy URLs: `/search?cat=3&sub=7&type=2&sort=date`
|
|
600
|
+
- Mixed conventions: `/Products/my_category/item-name` (case and separator inconsistency)
|
|
601
|
+
|
|
602
|
+
### 6.2 Routing Architecture
|
|
603
|
+
|
|
604
|
+
The IA informs application routing in single-page applications (SPAs) and server-rendered applications.
|
|
605
|
+
|
|
606
|
+
**Framework routing should mirror IA:**
|
|
607
|
+
```
|
|
608
|
+
/ → Home
|
|
609
|
+
/products → Product category listing
|
|
610
|
+
/products/:category → Product subcategory
|
|
611
|
+
/products/:category/:slug → Product detail
|
|
612
|
+
/about → About section
|
|
613
|
+
/about/team → Team page
|
|
614
|
+
/help → Help center
|
|
615
|
+
/help/:topic → Help topic
|
|
616
|
+
/help/:topic/:article → Help article
|
|
617
|
+
```
|
|
618
|
+
|
|
619
|
+
**Development considerations:**
|
|
620
|
+
- Route parameters should match IA concepts (category, topic, article) not database concepts (id, type)
|
|
621
|
+
- Nested routes should reflect IA hierarchy for correct breadcrumb generation
|
|
622
|
+
- Dynamic routes must handle invalid paths gracefully (404 pages with navigation, not dead ends)
|
|
623
|
+
- Consider route-based code splitting aligned with IA sections for performance
|
|
624
|
+
- API endpoint structure should parallel the IA for developer consistency
|
|
625
|
+
|
|
626
|
+
### 6.3 Breadcrumb Implementation
|
|
627
|
+
|
|
628
|
+
Breadcrumbs are a direct expression of the IA hierarchy in the UI. Implementation must align with the defined IA structure.
|
|
629
|
+
|
|
630
|
+
**Types of breadcrumbs:**
|
|
631
|
+
- Location-based — shows position in hierarchy (Home > Electronics > Headphones > Wireless)
|
|
632
|
+
- Attribute-based — shows applied filters (Electronics > Brand: Sony > Price: Under $100)
|
|
633
|
+
- Path-based — shows the user's actual navigation history (generally not recommended — browser back button serves this purpose)
|
|
634
|
+
|
|
635
|
+
**Implementation requirements:**
|
|
636
|
+
- Breadcrumbs must reflect the canonical IA location, not the user's navigation path
|
|
637
|
+
- Items in the breadcrumb should be clickable links (except the current page)
|
|
638
|
+
- The current page should be visually distinct (text only, not a link)
|
|
639
|
+
- Use `aria-label="Breadcrumb"` and `<nav>` element for accessibility
|
|
640
|
+
- Implement BreadcrumbList structured data (schema.org) for SEO
|
|
641
|
+
|
|
642
|
+
**Structured data example:**
|
|
643
|
+
```json
|
|
644
|
+
{
|
|
645
|
+
"@context": "https://schema.org",
|
|
646
|
+
"@type": "BreadcrumbList",
|
|
647
|
+
"itemListElement": [
|
|
648
|
+
{ "@type": "ListItem", "position": 1, "name": "Home", "item": "https://example.com/" },
|
|
649
|
+
{ "@type": "ListItem", "position": 2, "name": "Electronics", "item": "https://example.com/electronics" },
|
|
650
|
+
{ "@type": "ListItem", "position": 3, "name": "Headphones", "item": "https://example.com/electronics/headphones" }
|
|
651
|
+
]
|
|
652
|
+
}
|
|
653
|
+
```
|
|
654
|
+
|
|
655
|
+
### 6.4 SEO Implications
|
|
656
|
+
|
|
657
|
+
IA has direct and significant impact on search engine optimization. Search engines use site structure to understand content relationships and assign authority.
|
|
658
|
+
|
|
659
|
+
**IA and SEO alignment:**
|
|
660
|
+
|
|
661
|
+
| IA Element | SEO Impact |
|
|
662
|
+
|------------|-----------|
|
|
663
|
+
| Hierarchy depth | Pages closer to the root receive more link equity (crawl depth) |
|
|
664
|
+
| Internal linking | Links between related content distribute authority and signal relationships |
|
|
665
|
+
| URL structure | Clean, descriptive URLs improve click-through rates in search results |
|
|
666
|
+
| Breadcrumbs | BreadcrumbList schema enhances search result appearance with site hierarchy |
|
|
667
|
+
| Navigation labels | Navigation text serves as anchor text for internal links — use descriptive labels |
|
|
668
|
+
| Taxonomy/tags | Taxonomy pages can rank for category-level keywords |
|
|
669
|
+
| Duplicate content | Poor IA with content in multiple locations creates canonicalization issues |
|
|
670
|
+
| Site maps | XML sitemaps (distinct from HTML sitemaps) help search engines discover all pages |
|
|
671
|
+
| Orphaned pages | Pages with no internal links are difficult for search engines to discover and rank |
|
|
672
|
+
|
|
673
|
+
**Technical SEO considerations from IA:**
|
|
674
|
+
- Implement canonical URLs when content legitimately appears at multiple IA locations
|
|
675
|
+
- Use `rel="nofollow"` on faceted navigation links to prevent search engine crawl traps
|
|
676
|
+
- Ensure the IA allows search engines to reach any page within 3 clicks from the homepage
|
|
677
|
+
- Create hub pages for each major taxonomy category — these become keyword-targeting assets
|
|
678
|
+
- Plan 301 redirects for any URL changes to preserve search equity
|
|
679
|
+
- Monitor crawl stats in Google Search Console to verify search engines can traverse the IA
|
|
680
|
+
|
|
681
|
+
### 6.5 State Management & Navigation State
|
|
682
|
+
|
|
683
|
+
- Derive active/current navigation states from the current route, not separate state stores
|
|
684
|
+
- Compute breadcrumb data from route metadata, not hardcoded per page
|
|
685
|
+
- Support deep linking — users must be able to bookmark and share any IA location
|
|
686
|
+
- Reflect filter and facet states in the URL for shareability
|
|
687
|
+
- Ensure browser history (back/forward) works correctly with all navigation interactions
|
|
688
|
+
|
|
689
|
+
### 6.6 Accessibility in Navigation
|
|
690
|
+
|
|
691
|
+
- Wrap navigation in `<nav>` with `aria-label` distinguishing multiple nav regions
|
|
692
|
+
- Provide "Skip to main content" link as the first focusable element
|
|
693
|
+
- Use `aria-current="page"` on the active navigation item
|
|
694
|
+
- Use `aria-expanded` and `aria-haspopup` on expandable menus with full keyboard support
|
|
695
|
+
- Wrap breadcrumbs in `<nav aria-label="Breadcrumb">` using `<ol>` with `aria-current="page"` on the last item
|
|
696
|
+
- Manage focus on SPA page transitions — move focus to the new content area
|
|
697
|
+
|
|
698
|
+
---
|
|
699
|
+
|
|
700
|
+
## 7. Foundational References
|
|
701
|
+
|
|
702
|
+
### Key Texts
|
|
703
|
+
|
|
704
|
+
- **Rosenfeld, Morville, & Arango** — *Information Architecture: For the Web and Beyond* (4th ed., O'Reilly, 2015). The definitive text ("the polar bear book"). Defines the four systems and provides comprehensive methodology.
|
|
705
|
+
- **Abby Covert** — *How to Make Sense of Any Mess* (2014). Accessible introduction to IA thinking and the concept of intentional structure.
|
|
706
|
+
- **Dan Brown** — *Practical Design Discovery* and the Eight Principles of IA (objects, choices, disclosure, exemplars, front doors, multiple classifications, focused navigation, growth).
|
|
707
|
+
- **Andrea Resmini & Luca Rosati** — *Pervasive Information Architecture* (2011). Extends IA to cross-channel and physical-digital environments.
|
|
708
|
+
- **Indi Young** — *Mental Models* (2008). Methodology for understanding and aligning to user mental models.
|
|
709
|
+
|
|
710
|
+
### Key Organizations and Resources
|
|
711
|
+
|
|
712
|
+
- **Nielsen Norman Group (NNG)** — Research-based articles on IA, navigation, card sorting, tree testing. Top 10 IA Mistakes is essential reading.
|
|
713
|
+
- **Information Architecture Institute** — Professional community for IA practitioners.
|
|
714
|
+
- **Abby Covert's IA Heuristics** — Ten-principle evaluation framework from five historical sources.
|
|
715
|
+
- **Optimal Workshop** — Primary tool for card sorting (OptimalSort) and tree testing (Treejack).
|
|
716
|
+
|
|
717
|
+
---
|
|
718
|
+
|
|
719
|
+
## 8. Quick Reference Checklist
|
|
720
|
+
|
|
721
|
+
Use this checklist to evaluate and validate an information architecture. Each item should be verifiable through research, testing, or documentation review.
|
|
722
|
+
|
|
723
|
+
### Research & Discovery
|
|
724
|
+
|
|
725
|
+
- [ ] User mental models have been researched (card sorting, interviews, search log analysis)
|
|
726
|
+
- [ ] Content inventory has been completed and audited (ROT analysis done)
|
|
727
|
+
- [ ] Competitor/analogous IA has been analyzed for patterns and conventions
|
|
728
|
+
- [ ] Key user tasks have been identified and prioritized (top 5-10)
|
|
729
|
+
- [ ] User vocabulary has been documented from research, search logs, and support data
|
|
730
|
+
- [ ] Stakeholder requirements and constraints have been gathered
|
|
731
|
+
|
|
732
|
+
### Structure & Organization
|
|
733
|
+
|
|
734
|
+
- [ ] Top-level categories reflect user mental models, not org structure
|
|
735
|
+
- [ ] Hierarchy depth does not exceed 3-4 levels for most content
|
|
736
|
+
- [ ] Every content item has a clear, logical home in the hierarchy
|
|
737
|
+
- [ ] Polyhierarchy is used where items genuinely belong in multiple categories
|
|
738
|
+
- [ ] Content types are defined with clear schemas and relationships
|
|
739
|
+
- [ ] Growth has been planned for — structure accommodates future content without rework
|
|
740
|
+
|
|
741
|
+
### Labeling & Vocabulary
|
|
742
|
+
|
|
743
|
+
- [ ] Navigation labels have been tested with users (tree testing, preference testing)
|
|
744
|
+
- [ ] Labels use user language, not internal jargon or branded terminology
|
|
745
|
+
- [ ] Labels are consistent across all navigation systems (global, local, footer, breadcrumbs)
|
|
746
|
+
- [ ] A controlled vocabulary or taxonomy has been defined and documented
|
|
747
|
+
- [ ] Synonyms are mapped so search handles vocabulary variations
|
|
748
|
+
- [ ] Labels are front-loaded with the most meaningful word
|
|
749
|
+
|
|
750
|
+
### Navigation Systems
|
|
751
|
+
|
|
752
|
+
- [ ] Global navigation is limited to 5-9 items and is consistent across all pages
|
|
753
|
+
- [ ] Local navigation is defined for each major section
|
|
754
|
+
- [ ] Breadcrumbs are implemented and reflect the IA hierarchy correctly
|
|
755
|
+
- [ ] Contextual navigation (related content) connects items across sections
|
|
756
|
+
- [ ] Mobile navigation has been designed and tested (not just a collapsed desktop nav)
|
|
757
|
+
- [ ] Utility navigation (search, account, help) is consistently placed
|
|
758
|
+
- [ ] Footer provides secondary access to key pages and sections
|
|
759
|
+
|
|
760
|
+
### Search
|
|
761
|
+
|
|
762
|
+
- [ ] Search scope and indexed content have been defined
|
|
763
|
+
- [ ] Zero-results state provides helpful alternatives (suggestions, popular content)
|
|
764
|
+
- [ ] Search results include relevant metadata (content type, date, section)
|
|
765
|
+
- [ ] Faceted filtering is available for content-rich search results
|
|
766
|
+
- [ ] Synonym handling is implemented (thesaurus or equivalent)
|
|
767
|
+
- [ ] Search logs are monitored regularly for gaps and vocabulary mismatches
|
|
768
|
+
|
|
769
|
+
### Validation & Testing
|
|
770
|
+
|
|
771
|
+
- [ ] Tree testing shows 80%+ success rate on key tasks
|
|
772
|
+
- [ ] First-click accuracy is above 60% on critical navigation paths
|
|
773
|
+
- [ ] Usability testing has validated navigation with representative users
|
|
774
|
+
- [ ] Analytics confirm users can find high-priority content (low bounce, task completion)
|
|
775
|
+
- [ ] Accessibility audit confirms navigation meets WCAG 2.2 AA requirements
|
|
776
|
+
- [ ] Cross-device testing validates IA works on mobile, tablet, and desktop
|
|
777
|
+
|
|
778
|
+
### Development Integration
|
|
779
|
+
|
|
780
|
+
- [ ] URL structure mirrors the IA hierarchy
|
|
781
|
+
- [ ] Application routing aligns with IA structure
|
|
782
|
+
- [ ] Breadcrumb structured data (schema.org BreadcrumbList) is implemented
|
|
783
|
+
- [ ] 301 redirects are planned for any changed URLs
|
|
784
|
+
- [ ] XML sitemap is generated and submitted to search engines
|
|
785
|
+
- [ ] Canonical URLs are set for content appearing at multiple IA locations
|
|
786
|
+
- [ ] Internal linking strategy distributes authority to key pages
|
|
787
|
+
- [ ] Navigation components are accessible (landmarks, ARIA, keyboard support)
|
|
788
|
+
|
|
789
|
+
### Governance & Maintenance
|
|
790
|
+
|
|
791
|
+
- [ ] Content governance process requires IA placement for new content
|
|
792
|
+
- [ ] Taxonomy governance assigns ownership for term management
|
|
793
|
+
- [ ] Regular content audits are scheduled (quarterly or semi-annually)
|
|
794
|
+
- [ ] Orphaned content checks are automated (crawler-based)
|
|
795
|
+
- [ ] Search log review is scheduled (monthly minimum)
|
|
796
|
+
- [ ] IA documentation (site map, taxonomy, content model) is maintained as living artifacts
|
|
797
|
+
|
|
798
|
+
---
|
|
799
|
+
|
|
800
|
+
*This module provides the foundational knowledge for evaluating, designing, and implementing information architecture across digital products. Apply these principles in conjunction with user research, content strategy, and interaction design to create structures that serve both users and organizational goals.*
|