Custom CSS: Differences in Classic and Next-Gen

🚧
Coming Soon! We're still putting the finishing touches on this feature

Overview

The transition from Classic Knack Apps to Next-Gen Apps represents a fundamental shift in how Knack applications are structured, styled, and experienced by users. This guide details changes between the two versions, providing developers with knowledge of changes needed if you want to use your existing CSS from Classic and implement it in Next-Gen successfully.

While the Next-Gen CSS is different from the Classic CSS, our goal is to provide substantial benefits in terms of user experience, user interface consistency, and long-term maintainability.

Important Notes:

JavaScript customization capabilities are planned for future releases, so this guide focuses on CSS and HTML structure changes.

Each Knack version (Classic and Next-Gen) maintains separate custom code. Changes in one version are completely isolated from the other.

Fundamental Architecture Changes

The most significant change in Next-Gen Apps is the shift from a presentation-focused structure to a semantic approach. This change affects different aspects of how applications are customized through CSS.

HTML Structure Changes

Classic Knack Apps use generic HTML elements with descriptive CSS classes. Next-Gen Apps use semantic HTML5 elements where appropriate.

Document Structure: Classic apps use <body> with the knack-body class as the primary container. Next-Gen Apps use <body> with the kn-app class, maintaining the same functional role while adopting the new naming convention.

Header Elements: The header structure has changed. Classic apps use <header> with the knHeader class for both desktop and mobile headers. Next-Gen Apps differentiate between desktop (kn-header) and mobile (kn-header-mobile) headers, both using the semantic <header> element but with distinct styling hooks.

Page Structure: Classic apps organize content using <div> elements with classes like kn-scene and kn-container. Next-Gen Apps use semantic elements: <main> for the primary page content (kn-page) and <div> for the page container (kn-page-container).

CSS Class System Changes

The CSS class naming system has been redesigned to provide better consistency, predictability, and organization.

Naming Convention: Classic apps use various naming patterns including knHeader, kn-container, and knHeader__mobile-nav-toggle. Next-Gen Apps use a consistent kn- prefix followed by descriptive names to more clearly indicate the element's purpose and hierarchy.

Hierarchical Organization: Next-Gen classes follow a logical hierarchy to help make relationships between elements clear. For example, navigation elements progress from kn-main-nav to kn-main-nav-item to kn-main-nav-toggle, creating an intuitive naming structure.

Navigation System Changes

The navigation system demonstrates the most comprehensive changes between Classic and Next-Gen Apps, with improvements in both structure and functionality.

Main Navigation

Next-Gen navigation uses semantic HTML with the <nav> element for the main navigation (kn-main-nav). Navigation items use <button> elements (kn-main-nav-item).

Container Structure: Next-Gen Apps provide specific containers for different navigation contexts: kn-main-nav-container for the primary navigation wrapper, kn-main-nav-vertical-container for vertical layouts, and kn-main-nav-mobile-container for mobile-specific navigation.

Mobile Navigation: Next-Gen Apps use kn-main-nav-mobile with a <div> element, maintaining the same HTML structure while providing clearer naming. The mobile navigation toggle changed from knHeader__mobile-nav-toggle to kn-main-nav-toggle, both using <button> elements for proper accessibility.

New Navigation Features

Next-Gen Apps introduce several navigation features that have no Classic equivalent:

Navigation Item Groups: The kn-main-nav-mobile-item-group class allows for organizing related navigation items, particularly useful in mobile layouts where grouping improves usability.

Profile Navigation: User profile navigation is enhanced with two distinct classes: kn-main-nav-profile-trigger for the profile menu button and kn-main-nav-profile-content for the profile menu content.

Brand Elements: The brand area changed from knHeader__title-logo-wrapper using an <a> element to kn-brand using a <div> element, providing more flexibility for brand content that may not be linked.

Page Content Structure

Page content organization shows improvements in semantic structure.

Page Organization

Next-Gen Apps use kn-page with the semantic <main> element, providing better document structure.

Page Containers: The page container changed from kn-container to kn-page-container, both using <div> elements but with more specific naming that clearly indicates the container's purpose.

Page Sections: Next-Gen Apps use kn-page-section with semantic <section> elements, providing better document structure.

Section Columns: Column organization improved from view-column to kn-page-section-column, both using <div> elements but with clearer naming that indicates the hierarchical relationship.

Page Elements

Several page elements show more semantic design:

Page Titles: Classic page titles used kn-title with <h2> elements. Next-Gen Apps use kn-page-title with <h1> elements, providing proper heading hierarchy.

Breadcrumbs: Navigation breadcrumbs changed from kn-crumbtrail to kn-breadcrumbs, both using <div> elements but with more descriptive naming.

Error Handling: Next-Gen Apps introduce new error handling elements that have no Classic equivalent: kn-page-error and kn-error-banner, both using <div> elements to provide better error messaging and user feedback.

404 Pages: The kn-page-not-found class uses a <main> element for 404 and similar error pages, providing semantic structure for error states.

View System Changes

The view system represents the core of Knack applications, and Next-Gen Apps introduce improvements while maintaining functional compatibility.

Base View Structure

The base view structure maintains the kn-view class with <div> elements, ensuring compatibility with existing styling patterns. However, view-specific classes have been enhanced for better organization and functionality.

View Headers: View headers changed from view-header to kn-view-header, both using <div> elements and with consistent naming that follows the new convention.

View Toolbars: The toolbar area changed from kn-records-nav to kn-view-toolbar, providing clearer naming that indicates the element's purpose rather than its technical implementation.

Form Views

Form views demonstrate the most significant semantic changes:

Form Containers: Classic form views used kn-form with <div> elements. Next-Gen Apps use kn-form-view with semantic <form> elements, providing better form validation, and browser behavior.

Form Layout: Next-Gen Apps introduce kn-form-view-single-column-wrapper for single-column layouts, a feature not available in Classic apps. Form columns changed from kn-form-col with <li> elements to kn-form-view-column with <div> elements, providing more flexible styling options.

Data Display Views

Data display views show consistent improvements in naming and structure:

List Views: List views changed from kn-list to kn-list-view, maintaining <div> elements while providing clearer naming. List columns changed from kn-list-container column to kn-list-view-column, eliminating the compound class structure for simpler targeting.

Detail Views: Detail views changed from kn-details to kn-details-view, and detail columns evolved from kn-details-column to kn-details-view-column, both maintaining <div> elements while providing consistent naming patterns.

Table Views: Table views maintain the semantic <table> element but with better organization. The main table changed from kn-table to kn-table-view, while new wrapper classes provide better responsive behavior: kn-table-view-wrapper and kn-table-view-container.

Chart and Report Views

Chart views show organizational improvements:

Report Views: The base report view changed from kn-report to kn-report-view, both using <div> elements but with clearer naming.

Chart Types: Next-Gen Apps provide specific classes for each chart type:

kn-pie-chart-view for pie charts
kn-area-chart-view for area charts
kn-line-chart-view for line charts
kn-bar-chart-view for bar charts
kn-bar-horizontal-chart-view for horizontal bar charts

Chart Headers: Next-Gen Apps introduce kn-chart-view-header for chart titles and headers, a feature not available in Classic apps.

Specialized Views

Several specialized views have more specific and functional naming:

Map Views: Map views changed from kn-map to kn-map-view, with different sub-components:

Map search: kn-map-search to kn-map-view-search (now using <form> instead of <div>)
Map results: kn-map-results to kn-map-view-results
Map list: kn-map-list to kn-map-view-results-list
Map render: kn-google-map to kn-map-view-results-render

Calendar Views: Calendar views changed from kn-calendar to kn-calendar-view, maintaining <div> elements while providing consistent naming.

Menu Views: Link group elements changed from kn-menu to kn-menu-view, both using <div> elements but with clearer naming that indicates the view type.

Rich Text Views: Rich text elements changed from kn-rich_text to kn-rich-text-view, maintaining <div> elements while improving naming consistency.

Search Views: Search elements changed from kn-search to kn-search-view, both using <div> elements but with naming that clearly indicates the view type.

Action Elements and Interactivity

Action elements show important improvements in semantic structure.

Button Changes

Classic action buttons used kn-link with <a> elements regardless of their function. Next-Gen Apps use kn-action-button with either <a> or <button> elements depending on the action type, providing better semantic meaning.

Buttons are used for actions that trigger functionality, while links are used for navigation, following web accessibility best practices.

Taking CSS from Classic into Next-Gen

Taking existing custom code from Classic and implementing it in Next-Gen Apps requires a systematic approach that addresses each aspect of the changes.

Note: Each Knack version (Classic and Next-Gen) maintains separate custom code. Changes in one version are completely isolated from the other.

CSS Change Process

Class Name Updates: The most straightforward migration task involves updating CSS selectors to use the new class names. This process can be largely automated using find-and-replace operations, but requires careful attention to ensure all instances are updated correctly.

Semantic HTML Considerations: Some styling may need adjustment due to the change in HTML elements. For example, styles targeting <h2> elements for page titles will need to be updated to target <h1> elements in Next-Gen Apps.

New Feature Integration: Take advantage of new classes and features that weren't available in Classic apps, such as navigation item groups, chart-specific classes, and enhanced error handling elements.

Testing and Validation

Cross-Browser Testing: Test all customizations across different browsers to ensure compatibility with the new semantic structure.

Accessibility Testing: Use accessibility testing tools to verify that customizations maintain or improve accessibility features.

Responsive Testing: Test all customizations across different screen sizes to ensure responsive behavior works correctly with the new structure.

Performance Testing: Verify that the migration doesn't negatively impact application performance.

JavaScript Considerations

Current Limitations: Next-Gen Apps do not currently support JavaScript customization. JavaScript customization capabilities are planned for future releases of Next-Gen Apps. When available, these will work with the semantic HTML structure and new CSS classes documented in this guide.

Best Practices for Next-Gen Development

Developing for Next-Gen Apps requires adopting new best practices that take advantage of the improved structure and capabilities.

Semantic HTML Utilization

Leverage Semantic Elements: Take advantage of the semantic HTML structure for more specific and meaningful CSS selectors. Use element selectors in combination with class selectors for more precise targeting.

Accessibility First: Design and develop with accessibility in mind from the beginning. The semantic structure provides a foundation for accessible applications, but custom code should be tested to ensure accessibility standards are met.

CSS Organization

Follow Naming Conventions: Use the kn- prefix for any custom classes to maintain consistency with the system naming convention.

Component-Based Styling: Organize CSS around the view components and semantic structure for better maintainability.

Optimization

Efficient Selectors: Use class selectors rather than complex descendant selectors for better performance.

Complete Mapping Reference

The following comprehensive table provides a complete mapping between Classic and Next-Gen implementations, serving as a quick reference for CSS development tasks.

UI Element	Classic CSS Class	Classic HTML Tag	Next-Gen CSS Class	Next-Gen HTML Tag	Change Notes
App	`knack-body`	`<body>`	`kn-app`	`<body>`	Simple class name change
Header	`knHeader`	`<header>`	`kn-header`	`<header>`	Consistent naming convention
Header Mobile	`knHeader`	`<header>`	`kn-header-mobile`	`<header>`	New mobile-specific class
Main Nav Vertical	Not available	N/A	`kn-main-nav-vertical-container`	`<div>`	New feature
Main Nav Container	`kn-container`	`<div>`	`kn-main-nav-container`	`<div>`	More specific naming
Main Nav Menu	`knHeader__menu`	`<div>`	`kn-main-nav`	`<nav>`	Semantic HTML change
Main Nav Container Mobile	Not available	N/A	`kn-main-nav-mobile-container`	`<div>`	New feature
Main Nav Mobile	`knHeader__mobile-nav`	`<div>`	`kn-main-nav-mobile`	`<div>`	Consistent naming
Main Nav Hamburger Toggle	`knHeader__mobile-nav-toggle`	`<button>`	`kn-main-nav-toggle`	`<button>`	Simplified naming
Main Nav Item	`knHeader__mobile-nav-list-item`	`<li>`	`kn-main-nav-item`	`<button>`	Semantic HTML change
Main Nav Item Group	Not available	N/A	`kn-main-nav-mobile-item-group`	`<div>`	New feature
Main Nav Profile	`kn-current_user`	`<div>`	`kn-main-nav-profile-trigger`	`<button>`	Semantic HTML change
Main Nav Profile Content	Not available	N/A	`kn-main-nav-profile-content`	`<div>`	New feature
Main Nav Brand	`knHeader__title-logo-wrapper`	`<a>`	`kn-brand`	`<div>`	More flexible structure
Page Container	`kn-container`	`<div>`	`kn-page-container`	`<div>`	More specific naming
Page	`kn-scene`	`<div>`	`kn-page`	`<main>`	Semantic HTML change
Page Breadcrumbs	`kn-crumbtrail`	`<div>`	`kn-breadcrumbs`	`<div>`	Clearer naming
Page Error	Not available	N/A	`kn-page-error`	`<div>`	New feature
Error Banner	Not available	N/A	`kn-error-banner`	`<div>`	New feature
Page Title	`kn-title`	`<h2>`	`kn-page-title`	`<h1>`	Proper heading hierarchy
Page Section	`kn-section`	`<div>`	`kn-page-section`	`<section>`	Semantic HTML change
Page Section Column	`view-column`	`<div>`	`kn-page-section-column`	`<div>`	Consistent naming
Page Not Found	Not available	N/A	`kn-page-not-found`	`<main>`	New feature
View	`kn-view`	`<div>`	`kn-view`	`<div>`	No change
View Header	`view-header`	`<div>`	`kn-view-header`	`<div>`	Consistent naming
View Toolbar	`kn-records-nav`	`<div>`	`kn-view-toolbar`	`<div>`	Clearer naming
Report View	`kn-report`	`<div>`	`kn-report-view`	`<div>`	Consistent naming
Pie Chart Element	`kn-report-rendered`	`<div>`	`kn-pie-chart-view`	`<div>`	Specific chart targeting
Area Chart Element	`kn-report-rendered`	`<div>`	`kn-area-chart-view`	`<div>`	Specific chart targeting
Line Chart Element	`kn-report-rendered`	`<div>`	`kn-line-chart-view`	`<div>`	Specific chart targeting
Bar Chart Element	`kn-report-rendered`	`<div>`	`kn-bar-chart-view`	`<div>`	Specific chart targeting
Bar Horizontal Chart Element	`kn-report-rendered`	`<div>`	`kn-bar-horizontal-chart-view`	`<div>`	Specific chart targeting
Chart Element Header	Not available	N/A	`kn-chart-view-header`	`<div>`	New feature
Form Element	`kn-form`	`<div>`	`kn-form-view`	`<form>`	Semantic HTML change
Form Element Single Column	Not available	N/A	`kn-form-view-single-column-wrapper`	`<div>`	New feature
Form Element Column	`kn-form-col`	`<li>`	`kn-form-view-column`	`<div>`	HTML structure change
Action Button	`kn-link`	`<a>`	`kn-action-button`	`<a>` or `<button>`	Semantic HTML change
List Element	`kn-list`	`<div>`	`kn-list-view`	`<div>`	Consistent naming
List Element Column	`kn-list-container column`	`<div>`	`kn-list-view-column`	`<div>`	Simplified class structure
Details Element	`kn-details`	`<div>`	`kn-details-view`	`<div>`	Consistent naming
Details Element Column	`kn-details-column`	`<div>`	`kn-details-view-column`	`<div>`	Consistent naming
Map Element	`kn-map`	`<div>`	`kn-map-view`	`<div>`	Consistent naming
Map Element Search	`kn-map-search`	`<div>`	`kn-map-view-search`	`<form>`	Semantic HTML change
Map Element Results	`kn-map-results`	`<div>`	`kn-map-view-results`	`<div>`	Consistent naming
Map Element Results List	`kn-map-list`	`<div>`	`kn-map-view-results-list`	`<div>`	Hierarchical naming
Map Element Results Render	`kn-google-map`	`<div>`	`kn-map-view-results-render`	`<div>`	Platform-agnostic naming
Calendar Element	`kn-calendar`	`<div>`	`kn-calendar-view`	`<div>`	Consistent naming
Table Element	`kn-table`	`<table>`	`kn-table-view`	`<table>`	Consistent naming
Table Element Wrapper	`kn-table-wrapper`	`<div>`	`kn-table-view-wrapper`	`<div>`	Consistent naming
Table Element Container	`kn-table`	`<div>`	`kn-table-view-container`	`<div>`	Distinct from table element
Link Group Element	`kn-menu`	`<div>`	`kn-menu-view`	`<div>`	Consistent naming
Rich Text Element	`kn-rich_text`	`<div>`	`kn-rich-text-view`	`<div>`	Consistent naming and hyphenation
Search Element	`kn-search`	`<div>`	`kn-search-view`	`<div>`	Consistent naming

Changes between Classic and Next-Gen

Note: Each Knack version maintains separate custom code. Changes in one version are completely isolated from the other.

The following outlines changes needed when using existing Classic CSS code and implementing it in Next-Gen CSS code.

Breaking Changes:

Form elements changing from <div> to <form>
Page titles changing from <h2> to <h1>
Navigation items: removed <ul> and <li>
Main navigation changing from <div> to <nav>
Page content changing from <div> to <main>
Page sections changing from <div> to <section>

Functional Improvements:

Action buttons supporting both <a> and <button> elements
Map search changing from <div> to <form>
All class name changes requiring CSS updates

New Features:

New navigation features (vertical container, item groups, profile content)
New error handling elements
Chart-specific classes
Single-column form wrapper

Common CSS Patterns

CSS Selector Updates:

/* Classic */
.knHeader { /* styles */ }
.kn-form { /* styles */ }
.kn-report-rendered { /* styles */ }

/* Next-Gen */
.kn-header { /* styles */ }
.kn-form-view { /* styles */ }
.kn-pie-chart-view { /* styles */ } /* Now chart-specific */

HTML Structure Considerations:

/* Classic - targeting h2 for page titles */
.kn-title h2 { /* styles */ }

/* Next-Gen - now h1 for proper hierarchy */
.kn-page-title { /* styles */ }

Responsive Design:

/* Classic - generic container */
.kn-container {
    max-width: 1200px;
    margin: 0 auto;
}

/* Next-Gen - specific containers */
.kn-page-container {
    max-width: 1200px;
    margin: 0 auto;
}

.kn-main-nav-container {
    display: flex;
    justify-content: space-between;
    align-items: center;
}